Understanding OpenAPI → Axios
Turn the contract into a typed client.
What the codegen actually produces, the OpenAPI features that map cleanly, and where you still write code by hand.
The contract is the source.
OpenAPI (formerly Swagger) is a YAML or JSON document describing an HTTP API: paths, methods, parameters, request bodies, response shapes. Codegen tools read the contract and produce client code in any target language. Axios in TypeScript is the most common frontend target — every endpoint becomes a typed function whose argument shape and return type match the spec.
What gets generated.
For each path: a function named after the operationId(getUsers, createOrder). For each request: an interface with path/query/header parameters and (when applicable) a typed body. For each response: a discriminated union of the documented status codes. The output is a TypeScript module with no runtime code other than the Axios call itself; tree-shaking removes unused endpoints.
A worked endpoint.
OpenAPI: GET /users/{id} with path param id:string, returns200: User or 404: Error. Generated function:function getUser(id: string): Promise<User>, which internally callsaxios.get(`/users/${id}`). The function rejects on 404 because Axios rejects on non-2xx by default. Two lines of generated code; the call site is autocompleted in any TypeScript editor.
GET /users/{id}
OpenAPI → typed fn
path param → arg ; response → return type.
getUser(id: string): Promise<User>
= Spec-driven typed client
What maps cleanly.
Primitive types, enums, allOf composition, refs. Request bodies with content-type application/json or multipart/form-data. Path and query parameters with simple serialisation. Bearer / API-key auth via Axios interceptors. Most CRUD APIs come out ~95% complete with a single codegen run.
What still needs hand-work.
oneOf with discriminator (codegen often emits a union with no narrowing helpers). Polymorphic responses — endpoints that return different shapes based on a query param. Streaming endpoints (Server-Sent Events, chunked transfer). File uploads with custom progress callbacks. Pagination cursors when the spec describes them only in prose. Authentication flows beyond a static header — OAuth refresh, request signing. The codegen's docstrings flag the gaps; you fill them in.
Regenerate often.
The whole point of codegen is that you regenerate when the spec changes. CI should fail if the generated file is out of sync with the contract — typically by running codegen and checking git diff is empty. Teams that regenerate manually end up with drift; teams that commit the generated file and run a check ship updates confidently. The fetch client is then a deterministic projection of the contract, not a parallel implementation.