Need help with openapi-client-axios?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

anttiviljami
239 Stars 33 Forks MIT License 223 Commits 21 Opened issues

Description

JavaScript client library for consuming OpenAPI-enabled APIs with axios

Services available

!
?

Need anything else?

Contributors list

# 37,382
HTML
openapi
PHP
axios
154 commits
# 378,634
TypeScr...
express...
Express
openapi
8 commits
# 387,739
PHP
TypeScr...
axios
openapi
3 commits
# 319,025
Perl
Racket
emacs-l...
silver-...
1 commit

openapi-client-axios

CI Dependencies npm version npm downloads bundle size Total alerts Language grade: JavaScript License Sponsored Buy me a coffee

JavaScript client library for consuming OpenAPI-enabled APIs with axios. Types included.

Features

  • [x] Create API clients from OpenAPI v3 definitions
  • [x] 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)
  • [x] Built on top of the robust axios JavaScript library
  • [x] Isomorphic, works both in browser and Node.js
  • [x] Generate TypeScript definitions (.d.ts) for your APIs with full IntelliSense support

Documentation

See DOCS.md

Quick Start

npm install --save axios openapi-client-axios
yarn add axios 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); }

Client

OpenAPI Client Axios uses operationIds in OpenAPIv3 definitions to call API operations.

After initializing

OpenAPIClientAxios
, an axios client instance extended with OpenAPI capabilities is exposed.

Example:

javascript
const api = new OpenAPIClientAxios({ definition: 'https://example.com/api/openapi.json' });
api.init().then((client) => {
  client.updatePet(1, { age: 12 });
});

client
is an axios instance initialized 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.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' } });

Paths Dictionary

OpenAPI Client Axios also allows calling API operations via their path and HTTP method, using the paths dictionary.

Example:

client.paths['/pets'].get(); // GET /pets, same as calling client.getPets()
client.paths['/pets'].post(); // POST /pets
client.paths['/pets/{petId}'].put(1); // PUT /pets/1
client.paths['/pets/{petId}/owner/{ownerId}'].get({ petId: 1, ownerId: 2 }) ; // GET /pets/1/owner/2

This allows calling operation methods without using their operationIds, which may be sometimes preferred.

Generating type files (.d.ts)

TypeScript IntelliSense

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.
import { Client as PetStoreClient } from './client.d.ts';

const client = await api.init(); const client = await api.getClient();

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!

The Chilicorn

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.