typescript-routes-to-openapi ·

Generate OpenApi documentation and input validators with Ajv for express server from TypeScript project.

Installation

npm install --save-dev typescript-routes-to-openapi
npm install typescript-routes-to-openapi-server

Usage

Create configuration file

typescript-routes-to-openapi.json

{
  "openapi": {
    "info": {
      "version": "1.0.0",
      "title": "Swagger Petstore",
      "description": "A sample API that uses a petstore as an example to demonstrate features in the OpenAPI 3.0 specification",
      "termsOfService": "http://swagger.io/terms/",
      "contact": {
        "name": "Swagger API Team",
        "email": "apiteam@swagger.io",
        "url": "http://swagger.io"
      },
      "license": {
        "name": "Apache 2.0",
        "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
      }
    },
    "servers": [
      {
        "url": "http://petstore.swagger.io/api"
      }
    ]
  },
  "tsConfigPath": "tsconfig.json",
  "generateOpenApiSchema": true,
  "checkProgramForErrors": true,
  "schemaOutputDir": "./",
  "schemaOutputFileName": "openapi.json",
  "routesOutputDir": "generated",
  "routesOutputFileName": "routes.ts"
}

Create controller

import { createExpressRoute } from 'typescript-routes-to-openapi-server';

type NewPet = {
  name: string;
  tag?: string;
};

type Pet = NewPet & {
  id: number;
};

export class PetController {
  findPets = createExpressRoute<{
    path: '/pets';
    method: 'get';
    requestQuery: {
      /**
       * @description tags to filter by
       */
      tags?: string[];
      /**
       * @description maximum number of results to return
       */
      limit?: number;
    };
    /**
     * @description pet response
     */
    responseBody: Pet[];
  }>((req, res) => {
    res.send([
      {
        id: 1,
        name: 'Garfield',
        tag: 'cat',
      },
    ]);
  });

  /**
   * @description Returns a user based on a single ID, if the user does not have access to the pet
   * @openapi_operationId find pet by id
   */
  findPetById = createExpressRoute<{
    path: '/pets/:id';
    method: 'get';
    pathParams: {
      /**
       * @description ID of pet to fetch
       */
      id: number;
    };
    /**
     * @description pet response
     */
    responseBody: Pet;
  }>((req, res) => {
    res.send({
      id: 1,
      name: 'Garfield',
      tag: 'cat',
    });
  });

  /**
   * @description Creates a new pet in the store. Duplicates are allowed
   * @openapi_operationId addPet
   */
  addPet = createExpressRoute<{
    path: '/pets';
    method: 'post';
    /**
     * @description Pet to add to the store
     */
    requestBody: NewPet;
    /**
     * @description pet response
     */
    responseBody: Pet[];
  }>((req, res) => {
    res.send([
      {
        id: 1,
        name: 'Garfield',
        tag: 'cat',
      },
    ]);
  });
}

Generate routes and OpenApi document

npx typescript-routes-to-openapi generate

Include generated routes in your express application

import express from 'express';
import { generatedRoutes } from './generated/routes';

const app = express();
const PORT = 8888;

app.use(express.json());
app.use(generatedRoutes);

app.listen(PORT, () => {
  console.log('Listening on', PORT);
});

See example