Using the typescript-axios
template
The typescript-axios
template outputs a client SDK based on the axios that gives the following:
- Typed methods to call each endpoint
- Optionally, runtime response validation
It follows the standard axios
pattern of rejecting any response that isn’t 2xx
and thus can’t provide typed
error responses. If you’d like to have strong typing over your error responses consider using the typescript-fetch
template.
Runtime request parameter validation is not currently supported.
See integration-tests/typescript-axios for more samples.
Install dependencies
First install the CLI and the required runtime packages to your project:
npm i --dev @nahkies/openapi-code-generator
npm i axios @nahkies/typescript-axios-runtime
See also quick start guide
Run generation
Experimental support for runtime response validation is available behind the --enable-runtime-response-validation
flag.
npm run openapi-code-generator \
--input ./openapi.yaml \
--input-type openapi3 \
--output ./src/clients/some-service \
--template typescript-axios \
--schema-builder zod
Using the generated code
Running the above will output these files into ./src/clients/some-service
:
./client.ts
: exports a classApiClient
that implements methods for calling each endpoint./models.ts
: exports typescript types./schemas.ts
: exports runtime parsers using the chosenschema-builder
(defaultzod
)
Once generated usage should look something like this:
const client = new ApiClient({
// Pass a axios instance if you wish to use interceptors for auth, logging, etc
// axios: axios.create({...}),
basePath: `http://localhost:${address.port}`,
defaultHeaders: {
"Content-Type": "application/json",
Authorisation: "Bearer: <TOKEN>", // can pass auth headers here
},
})
// rejects if status code isn't 2xx, following typical axios behavior
const res = await client.createTodoListItem({
listId: list.id,
requestBody: {content: "test item"},
// optionally pass a timeout (ms), or any arbitrary axios options
// timeout?: number,
// opts?: AxiosRequestConfig
})
// data will be typed correctly
console.log(`id is: ${res.data.id}`)