openapi-client-axios

OpenAPI Client Axios

Fully typed client library for consuming OpenAPI-enabled APIs with axios

Features

• Create API clients by describing them in OpenAPI specification and importing them via YAML or JSON files or by just passing an object
• 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

Quick Start

npm install --save openapi-client-axios

With promises / CommonJS syntax:

const OpenAPIClientAxios = require('openapi-client-axios').default;

const api = new OpenAPIClientAxios({ definition: 'https://example.com/api/openapi.json' });
api.init()
  .then(client => client.getPetById(1))
  .then(res => console.log('Here is pet id:1 from the api', res.data));

With async-await / ES6 syntax:

import OpenAPIClientAxios from 'openapi-client-axios';

const api = new OpenAPIClientAxios({ definition: 'https://example.com/api/openapi.json' });
api.init();

async function createPet() {
  const client = await api.getClient();
  const res = await client.createPet(null, { name: 'Garfield' });
  console.log('Pet created', res.data);
}

Operation methods

OpenAPIClientAxios operation methods take 3 arguments:

client.operationId(parameters?, data?, config?)

Parameters

The first argument is used to pass parameters available for the operation.

// GET /pets/{petId}
client.getPet({ petId: 1 })

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} - getPet
client.getPet(1)

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 - searchPets
client.searchPets([{ name: 'search', value: 'Garfield', in: 'query' }])

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 - updatePet
client.updatePet(1, { name: 'Odie' })

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 - createPet
client.updatePet(null, { name: 'Garfield' })

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 - createUser
client.createUser(null, { user: 'admin', pass: '123' }, { headers: { 'x-api-key': 'secret' } });

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

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 of OpenAPIClient;

Both the api.getClient() and api.init() methods support passing in a Client type.

import { Client as PetStoreClient } from './client.d.ts';

const client = await api.init<PetStoreClient>();
const client = await api.getClient<PetStoreClient>();

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!