swagger

Swagger integration module for typescript express inspired from swagger-express-ts

Automatically generate and serve swagger.json v2.0.

Getting started

First, install ts-swagger-express.

npm install ts-swagger-express --save

Step 1: configure express

import * as express from "express";
import * as swagger from "ts-swagger-express";
import swaggerUi from 'swagger-ui-express';
const config = require ( "../config.json" );


// create server
const app = express();


    // generating swagger.json on /api-docs/swagger.json
    app.use(
        swagger.express({
            definition: {
                info: {
                    title: 'swagger Service Api',
                    version: '1.0',
                },
                schemes: ['http', 'https'],
                securityDefinitions: {
                    Bearer: {
                        type: 'apiKey',
                        in: 'header',
                        name: 'Authorization',
                    },
                },
                basePath: '/'
            },
        }),
    );

    // serving swagger ui from swagger.json path
    app.use(
        '/swagger',
        swaggerUi.serve,
        swaggerUi.setup(undefined, {
            swaggerOptions: {
                url: '/api-docs/swagger.json',
            },
        }),
    );


app.listen( config.port );
console.info( "Server is listening on port : " + config.port );

Step 2: Decorate your models

@ApiModel( {
    description : "Version description" ,
    name : "Version"
} )
export class VersionModel {

    @ApiModelProperty( {
        description : "Id of version" ,
        required : true,
        example: ['123456789']
    } )
    id : number;

    @ApiModelProperty( {
        description : "" ,
        required : true
    } )
    name : string;

    @ApiModelProperty( {
        description : "Description of version" ,
        required : true
    } )
    description : string;
}

Step 3: Decorate your controllers

@ApiPath({
    path: "/versions",
    name: "Version",
    security: { basicAuth: [] }
})
@controller("/versions")
@injectable()
export class VersionController implements interfaces.Controller {
    public static TARGET_NAME: string = "VersionController";
    
    private data = [{
            id: "1",
            name: "Version 1",
            description: "Description Version 1",
            version: "1.0.0"
        },
        {
            id: "2",
            name: "Version 2",
            description: "Description Version 2",
            version: "2.0.0"
        }];

    @ApiOperationGet({
        description: "Get versions objects list",
        summary: "Get versions list",
        responses: {
            200: { description: "Success", type: SwaggerDefinitionConstant.Response.Type.ARRAY, model: "Version" }
        },
        security: {
            apiKeyHeader: []
        }
    })
    @httpGet("/")
    public getVersions(request: express.Request, response: express.Response, next: express.NextFunction): void {
        response.json(this.data);
    }

    @ApiOperationPost({
        description: "Post version object",
        summary: "Post new version",
        parameters: {
            body: { description: "New version", required: true, model: "Version" }
        },
        responses: {
            200: { description: "Success" },
            400: { description: "Parameters fail" }
        }
    })
    @httpPost("/")
    public postVersion(request: express.Request, response: express.Response, next: express.NextFunction): void {
        if (!request.body) {
            return response.status(400).end();
        }
        this.data.push(request.body);
        response.json(request.body);
    }

}

Step 4: Test

• Start your server and test swagger.json on url : /api-docs/swagger.json
• test your swagger ui on url : /swagger

Project example

You can quickly find plenty of examples on ts-swagger-express github repository.

• Configuration
• @ApiModel
• @ApiModelProperty
• @ApiPath
• @ApiOperationGet
• @ApiOperationPost
• @ApiOperationPut
• @ApiOperationPatch
• @ApiOperationDelete

For any questions, suggestions, or feature requests

• you contact the author on ([email protected])