@ovotech/axios-oapi-cli

Axios Oapi

Generate types for REST apis, using information from OpenApi (Swagger) data.

Usage

You can install the package with yarn (or npm):

yarn add @ovotech/axios-oapi-cli --dev

Then given this OpenApi file:

examples/simple.yaml

---
openapi: 3.0.0
info:
  title: Test
  version: 1.0.0
servers:
  - url: https://simple.example.com
paths:
  '/test/{id}':
    parameters:
      - name: id
        in: path
        schema:
          type: string
        required: true

    post:
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/User' }
      responses:
        '200':
          description: A Test Object
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Test' }
    get:
      responses:
        '200':
          description: A Test Object
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Test' }

components:
  schemas:
    User:
      additionalProperties: false
      properties:
        email:
          type: string
        scopes:
          type: array
          items:
            type: string
      required:
        - email

    Test:
      properties:
        text:
          type: string
        user:
          $ref: '#/components/schemas/User'
      required:
        - text

You can run

yarn axios-oapi --file examples/simple.yaml --output examples/simple.types.ts

And would then have:

examples/simple.types.ts

import { AxiosRequestConfig, AxiosInstance, AxiosResponse } from "axios";

/**
 * Test
 *
 * Version: 1.0.0
 */
export const axiosOapi = (api: AxiosInstance): AxiosOapiInstance => ({
    "POST /test/{id}": (id, data, config) => api.post<Test>(`/test/${id}`, data, config),
    "GET /test/{id}": (id, config) => api.get<Test>(`/test/${id}`, config),
    api: api
});

export interface User {
    email: string;
    scopes?: string[];
}

export interface Test {
    text: string;
    user?: User;
    [key: string]: unknown;
}

export interface AxiosOapiInstance {
    "POST /test/{id}": (id: string, data: User, config?: AxiosRequestConfig) => Promise<AxiosResponse<Test>>;
    "GET /test/{id}": (id: string, config?: AxiosRequestConfig) => Promise<AxiosResponse<Test>>;
    api: AxiosInstance;
}

And you can then use it like this:

examples/simple.ts

import axios from 'axios';
import { axiosOapi } from './simple.types';
import * as nock from 'nock';

/**
 * Mock the simple rest api so we can test it out
 */
nock('http://simple.example.com')
  .get('/test/20')
  .reply(200, { text: 'test' })
  .post('/test/30')
  .reply(200, { text: 'test', user: { email: '[e-mail]' } });

/**
 * Wrap an axios instance. This will add typed functions with the name of the paths
 */
const simple = axiosOapi(axios.create({ baseURL: 'http://simple.example.com' }));

simple['GET /test/{id}']('20').then(({ data }) => console.log(data));

simple['POST /test/{id}']('30', { email: 'test2example.com' }).then(({ data }) =>
  console.log(data),
);

Complex example

If we use swagger's petstore.json example, we can generate the petstore types and use them like this:

examples/petstore.ts

import { axiosOapi } from './petstore.types';
import axios from 'axios';

const petstore = axiosOapi(axios.create({ baseURL: 'https://petstore.swagger.io/v2' }));

const main = async () => {
  const { data: pixel } = await petstore['PUT /pet']({
    name: 'Pixel',
    photoUrls: ['https://placekitten.com/g/200/300'],
    tags: [{ name: 'axios-oapi-cli' }],
  });

  console.log('SAVED', pixel);

  const { data: retrievedPixel } = await petstore['GET /pet/{petId}'](pixel.id!);

  console.log('RETRIEVED', retrievedPixel);

  // Use the underlying api to perform custom requests
  const { data: inventory } = await petstore.api.get('/store/inventory');
  console.log('INVENTORY', inventory);
};

main();

STDIN / STDOUT and piping

If you don't include "output" the cli will output to stdout. You can use this to chain with other processors like prettier

yarn axios-oapi --file examples/simple.yaml | prettier --stdin-filepath examples/simple.types.ts > examples/simple.types.ts

If you omit the "file" option, stdin will be used. This can be used to pipe the file contents from somewhere else (like curl). By default it will asume the content to be json.

curl http://example.com/simple.json | yarn axios-oapi --output examples/simple.types.ts

You can specify that the openapi content is yaml too:

curl http://example.com/simple.yaml | yarn axios-oapi --output examples/simple.types.ts --stdin-type yaml

Running the tests

You can run the tests with:

yarn test

Coding style (linting, etc) tests

Style is maintained with prettier and eslint

yarn lint

Deployment

Deployment is preferment by lerna automatically on merge / push to master, but you'll need to bump the package version numbers yourself. Only updated packages with newer versions will be pushed to the npm registry.

Contributing

Have a bug? File an issue with a simple example that reproduces this so we can take a look & confirm.

Want to make a change? Submit a PR, explain why it's useful, and make sure you've updated the docs (this file) and the tests (see test folder).

License

This project is licensed under Apache 2 - see the LICENSE file for details