swagger-express-ts

Automatically generate and serve swagger.json v2.0.

Getting started

First, install swagger-express-ts.

``sh
npm install swagger-express-ts --save
`

and init tsconfig.json

The Basics

In the examples below, we use inversify-express-utils. inversify-express-utils is not required to work with swagger-express-ts.

$3

`ts
import * as bodyParser from "body-parser";
import * as express from "express";
import "reflect-metadata";
import { Container } from "inversify";
import { interfaces, InversifyExpressServer, TYPE } from "inversify-express-utils";
import { VersionController } from "./version/version.controller";
import * as swagger from "swagger-express-ts";
import { SwaggerDefinitionConstant } from "swagger-express-ts";
const config = require ( "../config.json" );

// set up container
const container = new Container ();

// note that you must bind your controllers to Controller
container.bind ( TYPE.Controller )
.to( VersionController ).inSingletonScope().whenTargetNamed( VersionController.TARGET_NAME );

// create server
const server = new InversifyExpressServer ( container );

server.setConfig( ( app : any ) => {
app.use( '/api-docs/swagger' , express.static( 'swagger' ) );
app.use( '/api-docs/swagger/assets' , express.static( 'node_modules/swagger-ui-dist' ) );
app.use( bodyParser.json() );
app.use( swagger.express(
{
definition : {
info : {
title : "My api" ,
version : "1.0"
} ,
externalDocs : {
url : "My url"
}
// Models can be defined here
}
}
) );
} );

server.setErrorConfig( ( app : any ) => {
app.use( ( err : Error , request : express.Request , response : express.Response , next : express.NextFunction ) => {
console.error( err.stack );
response.status( 500 ).send( "Something broke!" );
} );
} );

const app = server.build();

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

`

$3

`ts
@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;
}
`

$3

`ts
@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);
}

}
`

$3

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

Extra

$3

You can serve swagger.json and swagger-ui in your API.

`sh
npm install swagger-ui-dist --save
`

Create index.html in new directory "swagger".

`html






rel="stylesheet">






style="position:absolute;width:0;height:0">






































`

Configure your server like that.

`ts
app.use( '/api-docs/swagger', express.static( 'swagger' ) );
app.use( '/api-docs/swagger/assets', express.static( 'node_modules/swagger-ui-dist' ) );
``

Test it on url "/api-docs/swagger".


Project example

You can quickly test swagger-express-ts with the project example example-swagger-express-ts.

Features and API

- Installation
- Configuration
- @ApiModel
- @ApiModelProperty
- @ApiPath
- @ApiOperationGet
- @ApiOperationPost
- @ApiOperationPut
- @ApiOperationPatch
- @ApiOperationDelete

For any questions, suggestions, or feature requests

Please file an issue!

Help wanted

swagger-express-ts wants additional maintainers! To maintain and continue to develop this young library, Please post in this issue.