Open Template Hub - Swagger Decorators v5

This library contains methods and decorators to ease and automate Swagger documentation.

Topics

• About the NPM Package
  • Package Installation
• Using OTH Swagger Decorators
  • @SwRoute
  • @SwTag
  • @SwSchema
  • @SwProp
  • @SwParam
  • @SwMethod
  • Full Route Example Including All Method Types
• Automation of Swagger Document Generation

About the NPM Package

Package Installation

npm install --save @open-template-hub/swagger-decorators

Using OTH Swagger Decorators

@SwRoute

This decorator helps you to define new route and can be specified on top of route class.

You must specify SwaggerRoute as the decorator argument.

import {
  SwaggerRoute,
  SwRoute,
} from '@open-template-hub/swagger-decorators';

const mySwaggerRoute = { name: 'MyRoute' } as SwaggerRoute;

@SwRoute( mySwaggerRoute )
export class MyRoute {
  /// Route Methods
}

@SwTag

This decorator helps you to define new tag and can be specified on top of Route class.

You must specify SwaggerRoute as the decorator argument.

import {
  SwaggerRoute,
  SwaggerTag,
  SwRoute,
  SwTag,
} from '@open-template-hub/swagger-decorators';

const mySwaggerRoute = { name: 'MyRoute' } as SwaggerRoute;

const mySwaggerTag = {
  name: 'MyTag',
  route: mySwaggerRoute,
} as SwaggerTag;

// Second tag under same route
const mySecondSwaggerTag = {
  name: 'MySecondTag',
  route: mySwaggerRoute,
} as SwaggerTag;

@SwRoute( mySwaggerRoute )
@SwTag( mySwaggerTag )
@SwTag( mySecondSwaggerTag )
export class MyRoute {
  /// Route Methods
}

@SwSchema

This decorator helps you to define new schema and can be specified on top of Schema class.

There are two types of Schema:

• Property Schema: Holds properties for Request Body and Response
• Parameter Schema: Holds parameters for Request Query and Path

You must specify SwaggerRoute as the first decorator argument for both Schema types.

The only difference for decoration, if you are defining a schema for parameters, you must set the second argument of @SwSchema, which is isParameterSchema, to true.

You can use Parameter Schema only with @SwParam parameters, and Property Schema can only be used with @SwProp properties.

Here you can see the example for Property Schema:

import {
  SwaggerRoute,
  SwSchema,
} from '@open-template-hub/swagger-decorators';

const mySwaggerRoute = { name: 'MyRoute' } as SwaggerRoute;

@SwSchema( mySwaggerRoute )
export class MySchema {
  // Schema Properties
}

Here you can see the example for Parameter Schema:

import {
  SwaggerRoute,
  SwSchema,
} from '@open-template-hub/swagger-decorators';

const mySwaggerRoute = { name: 'MyRoute' } as SwaggerRoute;

@SwSchema( mySwaggerRoute, true )
export class MyParameterSchema {
  // Schema Parameters
}

@SwProp

This decorator helps you to define new property and can be specified on top of Properties.

This decorator takes two arguments. First argument is the description of the property and set the second argument, which is required, to true if the property is required. You do not need to set anything for the second argument if the property is not required.

Default values set to property will be used as example.

import {
  SwaggerRoute,
  SwSchema,
  SwProp
} from '@open-template-hub/swagger-decorators';

const mySwaggerRoute = { name: 'MyRoute' } as SwaggerRoute;

@SwSchema( mySwaggerRoute )
export class MySchema {
  @SwProp( 'The source application or service', true )
  source: string = 'OTH Web UI';
  @SwProp( 'Event creation time', true )
  timestamp: number = 1666476669;
  @SwProp( 'Can contain any kind of data payload' )
  payload: any = { test: true };
}

@SwParam

This decorator helps you to define new parameter and can be specified on top of Parameters.

This decorator takes three arguments. First argument is the description of the parameter. Second argument specifies where this parameter will be stated, so it can be either PATH or QUERY and set the third argument, which is required, to true if the parameter is required. You do not need to set anything for the third argument if the parameter is not required.

Default values set to parameter will be used as example.

import {
  SwaggerRoute,
  SwSchema,
  SwParam,
  ParameterIn
} from '@open-template-hub/swagger-decorators';

const mySwaggerRoute = { name: 'MyRoute' } as SwaggerRoute;

@SwSchema( mySwaggerRoute, true )
export class MyParameterSchema {
  @SwParam( 'Filter for reporter', ParameterIn.QUERY )
  reporter: string = 'service-user';
  @SwParam( 'Limit for records to return', ParameterIn.QUERY, true )
  limit: number = 5;
}

@SwMethod

This decorator helps you to define new method and can be specified on top of route Methods. This decorator takes only one argument which is SwaggerMethod.

For better understanding, you can check all the properties for SwaggerMethod:

interface SwaggerMethod {
  // Swagger Route
  route: SwaggerRoute;

  // Method Name
  name: string;

  // Method Summary
  summary: string;

  // Method Description
  description: string;

  // Http Method: GET, POST, PUT, PATCH, DELETE
  httpMethod: HttpMethod;

  // Responses that method will return
  responses: Array<SwaggerResponse>;

  // Identifies the security scheme
  security?: SwaggerSecurityScheme;

  // Tags that method classified
  tags?: Array<SwaggerTag>;

  // Parameter schemas if you have in-query or in-path parameters
  parameterSchemas?: Array<string>;

  // Request Body
  requestBody?: SwaggerRequestBody;
}

Related Interfaces

• SwaggerRequestBody

interface SwaggerRequestBody {
  // Request body content
  content: SwaggerContent;

  // Is request body required
  required: boolean;
}

• SwaggerResponse

interface SwaggerResponse {
  // Response code
  responseCode: number;

  // Response description
  description: string;

  // Response content
  content: SwaggerContent;
}

• SwaggerTag

interface SwaggerTag {
  // Tag name
  name: string;

  // Swagger Route
  route: SwaggerRoute;
}

• SwaggerContent

interface SwaggerContent {
  // Related schema
  schema: SwaggerSchema;

  // Is the content array of schema?
  arrayOf?: boolean;
}

Full Route Example Including All Method Types

import {
  HttpMethod,
  ParameterIn,
  SwaggerMethod,
  SwaggerRequestBody,
  SwaggerResponse,
  SwaggerRoute,
  SwaggerSchema,
  SwaggerSecurityScheme,
  SwaggerTag,
  SwMethod,
  SwParam,
  SwProp,
  SwRoute,
  SwSchema,
  SwTag,
} from '@open-template-hub/swagger-decorators';

const mySwaggerRoute = { name: 'MyRoute' } as SwaggerRoute;

const mySwaggerTag = {
  name: 'MyTag',
  route: mySwaggerRoute,
} as SwaggerTag;

@SwSchema( mySwaggerRoute )
export class MySchema {
  @SwProp( 'The source application or service', true )
  source: string = 'OTH Web UI';
  @SwProp( 'Event creation time', true )
  timestamp: number = 1666476669;
  @SwProp( 'Can contain any kind of data payload' )
  payload: any = { test: true };
}

@SwSchema( mySwaggerRoute )
export class MyPatchSchema {
  @SwProp( 'Can contain any kind of data payload' )
  payload: any = { test: true };
}

@SwSchema( mySwaggerRoute, true )
export class MyParameterSchema {
  @SwParam( 'Filter for reporter', ParameterIn.QUERY )
  reporter: string = 'service-user';
  @SwParam( 'Limit for records to return', ParameterIn.QUERY, true )
  limit: number = 5;
}

@SwSchema( mySwaggerRoute, true )
export class MyDeleteSchema {
  @SwParam( 'Identifier of the object that will be deleted', ParameterIn.QUERY )
  id: string = '8034c607-a41d-4f29-8737-4cc9233a8b53';
}

@SwRoute( mySwaggerRoute )
@SwTag( mySwaggerTag )
export class MyRoute {

  @SwMethod( {
    httpMethod: HttpMethod.GET,
    route: {
      name: 'Sub-route name',
      parent: mySwaggerRoute,
    } as SwaggerRoute,
    name: 'myGet',
    summary: 'Summary of the method',
    description: 'Description of the method',
    security: SwaggerSecurityScheme.BEARER,
    tags: [ mySwaggerTag ],
    parameterSchemas: [ 'MyParameterSchema' ],
    responses: [
      {
        content: {
          schema: {
            name: 'MySchema',
            route: mySwaggerRoute,
          } as SwaggerSchema,
          arrayOf: true,
        },
        responseCode: 200,
        description: 'OK',
      } as SwaggerResponse,
    ],
  } as SwaggerMethod )
  myGet = () => {
    // Route method
  }

  @SwMethod( {
    httpMethod: HttpMethod.POST,
    route: {
      name: 'Sub-route name',
      parent: mySwaggerRoute,
    } as SwaggerRoute,
    name: 'myPost',
    summary: 'Summary of the method',
    description: 'Description of the method',
    security: SwaggerSecurityScheme.BEARER,
    tags: [ mySwaggerTag ],
    requestBody: {
      content: {
        schema: {
          name: 'MySchema',
          route: mySwaggerRoute,
        } as SwaggerSchema,
      },
      required: true,
    } as SwaggerRequestBody,
    responses: [
      {
        content: {
          schema: {
            name: 'MySchema',
            route: mySwaggerRoute,
          } as SwaggerSchema,
        },
        responseCode: 201,
        description: 'Created',
      } as SwaggerResponse,
    ],
  } as SwaggerMethod )
  myPost = () => {
    // Route method
  }

  @SwMethod( {
    httpMethod: HttpMethod.PUT,
    route: {
      name: 'Sub-route name',
      parent: mySwaggerRoute,
    } as SwaggerRoute,
    name: 'myPut',
    summary: 'Summary of the method',
    description: 'Description of the method',
    security: SwaggerSecurityScheme.BEARER,
    tags: [ mySwaggerTag ],
    requestBody: {
      content: {
        schema: {
          name: 'MySchema',
          route: mySwaggerRoute,
        } as SwaggerSchema,
      },
      required: true,
    } as SwaggerRequestBody,
    responses: [
      {
        content: {
          schema: {
            name: 'MySchema',
            route: mySwaggerRoute,
          } as SwaggerSchema,
        },
        responseCode: 200,
        description: 'Updated',
      } as SwaggerResponse,
    ],
  } as SwaggerMethod )
  myPut = () => {
    // Route method
  }

  @SwMethod( {
    httpMethod: HttpMethod.PATCH,
    route: {
      name: 'Sub-route name',
      parent: mySwaggerRoute,
    } as SwaggerRoute,
    name: 'myPatch',
    summary: 'Summary of the method',
    description: 'Description of the method',
    security: SwaggerSecurityScheme.BEARER,
    tags: [ mySwaggerTag ],
    requestBody: {
      content: {
        schema: {
          name: 'MyPatchSchema',
          route: mySwaggerRoute,
        } as SwaggerSchema,
      },
      required: true,
    } as SwaggerRequestBody,
    responses: [
      {
        content: {
          schema: {
            name: 'MySchema',
            route: mySwaggerRoute,
          } as SwaggerSchema,
        },
        responseCode: 200,
        description: 'Updated',
      } as SwaggerResponse,
    ],
  } as SwaggerMethod )
  myPatch = () => {
    // Route method
  }

  @SwMethod( {
    httpMethod: HttpMethod.DELETE,
    route: {
      name: 'Sub-route name',
      parent: mySwaggerRoute,
    } as SwaggerRoute,
    name: 'myDelete',
    summary: 'Summary of the method',
    description: 'Description of the method',
    security: SwaggerSecurityScheme.BEARER,
    tags: [ mySwaggerTag ],
    parameterSchemas: [ 'MyDeleteSchema' ],
    responses: [
      {
        content: {
          schema: {
            name: 'MySchema',
            route: mySwaggerRoute,
          } as SwaggerSchema,
        },
        responseCode: 200,
        description: 'Updated',
      } as SwaggerResponse,
    ],
  } as SwaggerMethod )
  myDelete = () => {
    // Route method
  }

}

Automation of Swagger Document Generation

Add this codeblock to your index file, to the place after Routes are mounted where you are starting node application. This codeblock will generate all Swagger Documents by reading decorators. Change 'app' with the folder name where you want to keep and load Swagger Documents

if ( process.env.OTH_SWAGGER_ON_GENERATION === 'true' ) {
  SwaggerDocumentation.getInstance().generateDocument(
      Path.join( __dirname, 'app' )
  );

  process.exit( 1 );
}

Add "swagger" command to package.json scripts

"scripts": {
    ...
    "swagger": "OTH_SWAGGER_ON_GENERATION=true npm start"
  }

You can use "swagger-ui-express" package to load Swagger UI from the generated "index.swagger" document spec.

npm i swagger-ui-express

if (
    process.env.OTH_SWAGGER_ON_GENERATION !== 'true'
) {
  const { SwaggerSpec } = require( './app/swagger/index.swagger' );
  const swaggerUi = require( 'swagger-ui-express' );
  const swaggerSpecification = new SwaggerSpec();
  app.use(
      '/docs',
      swaggerUi.serve,
      swaggerUi.setup( swaggerSpecification.getSpec() )
  );
}

And when your decorators are stated in your code and ready, you can run and automate simply the "swagger" command:

npm run swagger

Sponsors

No sponsors yet! Will you be the first?

Contributors

Furkan Yavuz 💬 📖 👀

Fatih Turker 💬 📖 👀

Mert Sarac 💬 📖 👀

Jérôme Poskin 💬 📖 👀

Contributing

Refer to CONTRIBUTING.md to see how to contribute to Open Template Hub.

Code of Conduct

Refer to CODE_OF_CONDUCT.md to see contributor covenant code of conduct.

LICENSE

The source code for this project is released under the MIT License.