Swagger-Mate

GrandLineX Swagger-Mate project

Status

Issues

Features

• Generate swagger.{json|yml} from code
• Generate Api client from swagger.{json|yml}

Quick Start

Install

1. Insatal npm package

  npm i  @grandlinex/swagger-mate

2. Update package.json

{
  //...
  "scripts": {
    "makeSpec": "swagger-mate",
    "serveSpec": "swagger-mate --serve",
    "buildSpecMain": "swagger-mate --build --main",
    "buildSpecDev": "swagger-mate --build --dev"
  },
  "glx": {
    "kernel": "dist/Kernel.js"
  }
  //...
}

|Command| Description | |---|-----------------------------------------------------------------------------------| |npm run makeSpec| make openapi.json | |npm run serveSpec| serve openapi.json with swagger-ui | |npm run buildSpecMain| build api client (prod) | |npm run buildSpecDev| build api client (dev) |

Serve option

Default port = 9000

ENV variables

| ENV | Description | |-----|--------------------------| | SW_PORT | set custom serve port | | SW_AUTH | set default bearer token |

Define types

Kernel

import { SPathUtil, Swagger } from '@grandlinex/swagger-mate';
// OpenApi 3.0.3 - Root Api definition
@Swagger({
  info: {
    title: 'KernelTest',
    version: '0.1.0', // Version (optional) will be read from package.json
  },
  openapi: '3.0.3',
  servers: [
    {
      url: 'http://localhost:9257',
      description: 'LocalDev',
    },
  ],
  paths: {
      // Static definition
    '/version': {
      get: {
        description: 'Get version',
        operationId: 'getVersion',
        responses: SPathUtil.defaultResponse('200', '500'),
      },
    },
   // Dynamic definition will be read from @SPath
  },
  security: [
    {
      bearerAuth: [],
    },
  ],
  components: {
    securitySchemes: {
      bearerAuth: {
        type: 'http',
        scheme: 'bearer',
        bearerFormat: 'JWT',
      },
    },
  },
})
export default class SomeKernel {}

Action

import { SPathUtil, Swagger } from '@grandlinex/swagger-mate';

// OpenApi 3.0.3 - Patch definition
@SPath({
    '/test': {
        get: {
            description: 'test',
            operationId: 'getTest', // name for the js api client
            summary: 'Descritption summary',
            responses: SPathUtil.defaultResponse('200','400', '500')
        },
    },
})
export default class SomeBaseApiAction {}