openapi-path-builder v0.0.3

openapi-path-builder

A simple fluent API for quickly building OpenAPI routes.

import Builder from 'openapi-path-builder';
const api = new Builder();

api.use
    .tags('Pets')
    .uriParamRef('petId', '#/definitions/petId')

api('/pet')
    .get('getAllPets')
    .sum('Get a lit of pets on sale')
    .res((res) => {
        res(200)
            .desc('A list of pets were returned')
            .schemaRef('#/definitions/ArrayOfPets');
    });

api('/pet/:petId')
    .post('addPet')
    .sum('Add a new pet to the store')
    .desc('Adding more pets means additional living merchandise for sale')
    .bodySchemaRef('#/definitions/addPetForm')
    .res((res) => {
        res(201)
            .desc('A new pet was added succesfully')
            .schemaRef('#/definitions/NewPetResponse');
        res(400).desc('Illegal pet type');
    })
    .get('getPet')
    .sum('Get a specific pet from the store')
    .res((res) => {
        res(200)
            .desc('A pet was returned')
            .schemaRef('#/definitions/NewPetResponse');
        res(404).desc('No such pet was found');
    });

Then, execute api.render() to produce:

{
  "/pet": {
    "get": {
      "tags": [
        "Pets"
      ],
      "operationId": "getAllPets",
      "summary": "Get a lit of pets on sale",
      "parameters": [],
      "responses": {
        "200": {
          "description": "A list of pets were returned",
          "schema": {
            "$ref": "#/definitions/ArrayOfPets"
          }
        }
      }
    }
  },
  "/pet/{petId}": {
    "post": {
      "tags": [
        "Pets"
      ],
      "description": "Adding more pets means additional living merchandise for sale",
      "operationId": "addPet",
      "summary": "Add a new pet to the store",
      "parameters": [
        {
          "name": "petId",
          "in": "path",
          "type": {
            "$ref": "#/definitions/petId/type"
          },
          "description": {
            "$ref": "#/definitions/petId/description"
          },
          "example": {
            "$ref": "#/definitions/petId/example"
          },
          "required": true
        },
        {
          "in": "body",
          "name": "body",
          "required": true,
          "schema": {
            "$ref": "#/definitions/addPetForm"
          }
        }
      ],
      "responses": {
        "201": {
          "description": "A new pet was added succesfully",
          "schema": {
            "$ref": "#/definitions/NewPetResponse"
          }
        },
        "400": {
          "description": "Illegal pet type"
        }
      }
    },
    "get": {
      "tags": [
        "Pets"
      ],
      "operationId": "getPet",
      "summary": "Get a specific pet from the store",
      "parameters": [
        {
          "name": "petId",
          "in": "path",
          "type": {
            "$ref": "#/definitions/petId/type"
          },
          "description": {
            "$ref": "#/definitions/petId/description"
          },
          "example": {
            "$ref": "#/definitions/petId/example"
          },
          "required": true
        }
      ],
      "responses": {
        "200": {
          "description": "A pet was returned",
          "schema": {
            "$ref": "#/definitions/NewPetResponse"
          }
        },
        "404": {
          "description": "No such pet was found"
        }
      }
    }
  }
}

Missing Features

There are a ton missing. More to come.

This package is an UNSTABLE work in progress - the behavior and/or semantics of this package could change at any time in the future.

PRs Welcome