OpenAPI Client Axios
JavaScript client library for consuming OpenAPI-enabled APIs with axios. Types included.
Features
- Create API clients from OpenAPI v3 definitions
- Easy to use API to call API operations using JavaScript methods
client.getPet(1)
client.searchPets()
client.searchPets({ ids: [1, 2, 3] })
client.updatePet(1, payload)
- Built on top of the robust axios JavaScript library
- Isomorphic, works both in browser and Node.js
- Generate TypeScript definitions (.d.ts) for your APIs with full IntelliSense support
Documentation
See DOCS.md
Quick Start
npm install --save openapi-client-axios
With promises / CommonJS syntax:
const OpenAPIClientAxios = default; const api = definition: 'https://example.com/api/openapi.json' ;api ;
With async-await / ES6 syntax:
; const api = definition: 'https://example.com/api/openapi.json' ;api; { const client = await api; const res = await client; console;}
Client
OpenAPI Client Axios uses operationIds in OpenAPIv3 definitions to call API operations.
After initalizing OpenAPIClientAxios
, an axios client instance extended with OpenAPI capabilities is exposed.
Example:
const api = definition: 'https://example.com/api/openapi.json' ;api;
client
is an axios instance initalized with
baseURL from OpenAPI definitions and extended with extra operation methods for calling API operations.
It also has a reference to OpenAPIClientAxios at client.api
Operation methods
OpenAPIClientAxios operation methods take 3 arguments:
client
Parameters
The first argument is used to pass parameters available for the operation.
// GET /pets/{petId}client
For syntactic sugar purposes, you can also specify a single implicit parameter value, in which case OpenAPIClientAxios will look for the first required parameter for the operation. Usually this is will be a path parameter.
// GET /pets/{petId} - getPetclient
Alternatively, you can explicitly specify parameters in array form. This method allows you to set custom parameters not defined in the OpenAPI spec.
// GET /pets?search=Garfield - searchPetsclient
The type of the parameters can be any of:
- query
- header
- path
- cookie
Data
The second argument is used to pass the requestPayload
// PUT /pets/1 - updatePetclient
More complex payloads, such as Node.js streams or FormData supported by Axios can be used.
The first argument can be set to null if there are no parameters required for the operation.
// POST /pets - createPetclient
Config object
The last argument is the config object.
The config object is an AxiosRequestConfig
object. You can use it to
override axios request config parameters, such as headers
, timeout
, withCredentials
and many more.
// POST /user - createUserclient;
Paths Dictionary
OpenAPI Client Axios also allows calling API operations via their path and HTTP method, using the paths dictionary.
Example:
clientpaths'/pets'; // GET /pets, same as calling client.getPets()clientpaths'/pets'; // POST /petsclientpaths'/pets/{petId}'; // PUT /pets/1clientpaths'/pets/{petId}/owner/{ownerId}' ; // GET /pets/1/owner/2
This allows calling operation methods without using their operationIds, which may be sometimes preferred.
Generating type files (.d.ts)
openapi-client-axios
comes with a tool called typegen
to generate typescript type files (.d.ts) for
OpenAPIClient instances using an OpenAPI definition file.
$ npm install -g openapi-client-axios-typegen
Usage: typegen [file]
Options:
--help Show help [boolean]
--version Show version number [boolean]
Examples:
typegen ./openapi.yml > client.d.ts - generate a type definition file
The output of typegen
exports a type called Client
, which can be used for instances created with OpenAPIClientAxios
.
Both the api.getClient()
and api.init()
methods support passing in a Client type.
; ;;
typegen
supports using both local and remote URLs for OpenAPI definition files.
$ typegen ./petstore.yaml
$ typegen https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml
Contributing
OpenAPI Client Axios is Free and Open Source Software. Issues and pull requests are more than welcome!