Nail Polishing Minions

    openapi-client-axios
    TypeScript icon, indicating that this package has built-in type declarations

    5.3.0 • Public • Published

    openapi-client-axios

    CI npm version npm downloads bundle size Total alerts Language grade: JavaScript License 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] Client is configured in runtime. No generated code!
    • [x] Generate TypeScript definitions (.d.ts) for your APIs with full IntelliSense support
    • [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

    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:

    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<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!

    Install

    npm i openapi-client-axios

    DownloadsWeekly Downloads

    21,993

    Version

    5.3.0

    License

    MIT

    Unpacked Size

    69.9 kB

    Total Files

    12

    Last publish

    Collaborators

    • anttiviljami