CHANGELOG.md

1.0.1

Features

example

Example:

...
@ApiModelProperty({
        description: 'Id of car',
        required: true,
        example: ['123456789', '12345'],
    })
    id: string;
    ...
}

or

...
app.use(
    swagger.express({
            ...
            models: {
                ApiError: {
                    properties: {
                        code: {
                            type:
                                SwaggerDefinitionConstant.Model.Property
                                    .Type.STRING,
                            example: ['400'],
                        },
                        message: {
                            type:
                                SwaggerDefinitionConstant.Model.Property
                                    .Type.STRING,
                            example: ['Name of car is required.'],
                        },
                    },
                },
            },
            ...
        },
    })
);
...

body in parameter

Example:

...
@ApiOperationPost({
    ...
    parameters: {
        body: {
            description: 'New car',
            required: true,
            model: 'Car',
        },
    },
    ...
})
...

or

...
@ApiOperationPost({
    ...
    parameters: {
        body: {
            required: true,
            properties: {
              name: { type: SwaggerDefinitionConstant.Parameter.Type.STRING, required: true}
            }
        },
    },
    ...
})
...

1.0.0

Features

itemType

Example:

...
@ApiModelProperty({
    description: "Name of author",
    required: true,
    itemType: SwaggerDefinitionConstant.Model.Property.Type.STRING
  })
name: string[];
...

or

...
app.use(
    swagger.express({
      definition: {
        ...
        models: {
          Author: {
               name: {
                 description: "Name of author",
                 type: SwaggerDefinitionConstant.Model.Property.Type.ARRAY,
                 itemType:
                   SwaggerDefinitionConstant.Model.Property.ItemType.STRING,
                 required: true
               }
             }
           }
        }
        ...
      }
    })
  );
...

1.0.0-rc.4

Features

Add global responses

Example:

swagger.express({
  definition: {
    ...
    responses: {
      500: {}
    },
    ...
  }
})

Fixes

Fix ApiModel when arg "name" and class name are equal.

1.0.0-rc.3

Fixes

Merge models and path

1.0.0-rc.2

Features

Name

Merge name when several controllers that point to the same name .

Example:

@ApiPath({
  path: "/versions",
  name: "Version"
})
...
export class VersionsController implements interfaces.Controller {
    ...
}

@ApiPath({
  path: "/versions/:id",
  name: "Version"
})
...
export class VersionController implements interfaces.Controller {
    ...
}

1.0.0-rc.1

Features

Model

Configuration

example:

definition : {
    ...
    models : {
        Version : {
            properties : {
                id : {
                    type : SwaggerDefinitionConstant.Model.Property.Type.STRING,
                    required : true
                },
                name : {
                    type : SwaggerDefinitionConstant.Model.Property.Type.STRING,
                    required : true
                },
                description : {
                    type : SwaggerDefinitionConstant.Model.Property.Type.STRING
                },
                version : {
                    type : SwaggerDefinitionConstant.Model.Property.Type.STRING
                },
                author: {
                    model: "Author"
                }
            }
        },
        Author: {
            properties: {
                id: {
                    type: SwaggerDefinitionConstant.Model.Property.Type.STRING,
                    required : true
                },
                name : {
                    type : SwaggerDefinitionConstant.Model.Property.Type.STRING,
                    required : true
                },
            }
        }
    },
    ...
}

or

@ApiModel({
    description: 'Version description',
    name: 'Version',
})
export class VersionModel {
    @ApiModelProperty({
        description: 'Id of version',
        required: true,
    })
    id: number;

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

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

    @ApiModelProperty({
        description: 'Author of version',
        model: 'Author',
    })
    author: AuthorModel;
}

Controller

example:

@ApiOperationGet( {
    ...
    responses : {
        200 : { description : "Success" , type : SwaggerDefinitionConstant.Response.Type.ARRAY , model : "Version" }
    } ,
    ...
} )

1.0.0-beta.1

Features

Authentication

Configuration

example:

app.use( swagger.express(
    {
        definition : {
            ...
            securityDefinitions : {
                basicAuth : {
                    type : SwaggerDefinitionConstant.Security.Type.BASIC_AUTHENTICATION
                },
                apiKeyHeader : {
                    type: SwaggerDefinitionConstant.Security.Type.API_KEY,
                    in: SwaggerDefinitionConstant.Security.In.HEADER,
                    name: "apiHeader"
                }
            }
        }
    }
) );

Basic Authentication

Example:

...
@ApiOperationGet( {
    ...
    security : {
        basicAuth : []
    }
} )
...

API Keys

Example:

...
@ApiOperationGet( {
    ...
    security : {
        apiKeyHeader : []
    }
} )
...

Operations as deprecated

Example in path:

...
@ApiPath( {
    ...
    deprecated: true
} )
...

Example in operation:

...
@ApiOperationGet( {
    ...
    deprecated: true
} )
...

1.0.0-alpha.5

Features

externalDocs

Example:

app.use(
    swagger.express({
        definition: {
            info: {
                title: 'My api',
                version: '1.0',
            },
            models: {
                Version: {
                    properties: {
                        id: {
                            type:
                                SwaggerDefinitionConstant.Model.Property.Type
                                    .STRING,
                            required: true,
                        },
                        name: {
                            type:
                                SwaggerDefinitionConstant.Model.Property.Type
                                    .STRING,
                            required: true,
                        },
                        description: {
                            type:
                                SwaggerDefinitionConstant.Model.Property.Type
                                    .STRING,
                        },
                        version: {
                            type:
                                SwaggerDefinitionConstant.Model.Property.Type
                                    .STRING,
                        },
                    },
                },
            },
            externalDocs: {
                url: 'My url',
            },
        },
    })
);

1.0.0-alpha.4

Add keywords for npm.

1.0.0-alpha.3

Complete informations.

1.0.0-alpha.2

Complete informations.

1.0.0-alpha.1

Complete informations.

1.0.0-alpha.0

Features

.express(options: ISwaggerExpressOptions)

Example:

app.use(
    swagger.express({
        definition: {
            setInfo: {
                title: 'My api',
                version: '1.0',
            },
            models: {
                Version: {
                    properties: {
                        id: {
                            type:
                                SwaggerDefinitionConstant.Definition.Property
                                    .Type.STRING,
                            required: true,
                        },
                        name: {
                            type:
                                SwaggerDefinitionConstant.Definition.Property
                                    .Type.STRING,
                            required: true,
                        },
                        description: {
                            type:
                                SwaggerDefinitionConstant.Definition.Property
                                    .Type.STRING,
                        },
                        version: {
                            type:
                                SwaggerDefinitionConstant.Definition.Property
                                    .Type.STRING,
                        },
                    },
                },
            },
        },
    })
);

@ApiPath(args: IApiPathArgs)

Example:

import { injectable } from 'inversify';
import 'reflect-metadata';
import { ApiPath } from 'swagger-express-ts';
import { controller } from 'inversify-express-utils';

@ApiPath({
    path: '/version',
    name: 'Version',
})
@controller('/version')
@injectable()
export class VersionController implements interfaces.Controller {
    public static TARGET_NAME: string = 'VersionController';
}

@ApiOperationDelete(args: IApiOperationDeleteArgs)

Example:

import * as express from 'express';
import { injectable } from 'inversify';
import {
    controller,
    interfaces,
    requestParam,
    httpDelete,
} from 'inversify-express-utils';
import {
    ApiPath,
    ApiOperationDelete,
    SwaggerDefinitionConstant,
} from 'swagger-express-ts';
import 'reflect-metadata';

@ApiPath({
    path: '/versions',
    name: 'Version',
})
@controller('/versions')
@injectable()
export class VersionController implements interfaces.Controller {
    public static TARGET_NAME: string = 'VersionController';
    private data: [any] = [
        {
            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',
        },
    ];

    @ApiOperationDelete({
        path: '/{id}',
        parameters: {
            path: {
                id: {
                    description: 'Id of version',
                    type: SwaggerDefinitionConstant.Parameter.Type.STRING,
                    required: true,
                },
            },
        },
        responses: {
            200: { description: 'Success' },
        },
    })
    @httpDelete('/:id')
    public deleteVersion(
        @requestParam('id') id: string,
        request: express.Request,
        response: express.Response,
        next: express.NextFunction
    ): void {
        this.data.forEach((version: any, index: number) => {
            if (version.id === id) {
                this.data.splice(index, 1);
                return response.status(200).end();
            }
        });
        response.status(404).end();
    }
}

@ApiOperationGet(args: IApiOperationGetArgs)

Decorate method for getting a resource in your controller.

Example:

import * as express from 'express';
import { injectable } from 'inversify';
import {
    controller,
    interfaces,
    requestParam,
    httpGet,
} from 'inversify-express-utils';
import {
    ApiPath,
    ApiOperationGet,
    SwaggerDefinitionConstant,
} from 'swagger-express-ts';
import 'reflect-metadata';

@ApiPath({
    path: '/versions',
    name: 'Version',
})
@controller('/versions')
@injectable()
export class VersionController implements interfaces.Controller {
    public static TARGET_NAME: string = 'VersionController';
    private data: [any] = [
        {
            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 version object',
        summary: 'Get version',
        responses: {
            200: { description: 'Success', isArray: true, model: 'Version' },
        },
    })
    @httpGet('/')
    public getVersions(
        request: express.Request,
        response: express.Response,
        next: express.NextFunction
    ): void {
        response.json(this.data);
    }
}

@ApiOperationPatch(args: IApiOperationPatchArgs)

Decorate method for updating a field of resource in your controller.

Example:

import * as express from 'express';
import { injectable } from 'inversify';
import {
    controller,
    interfaces,
    requestParam,
    httpPatch,
} from 'inversify-express-utils';
import {
    ApiPath,
    ApiOperationPatch,
    SwaggerDefinitionConstant,
} from 'swagger-express-ts';
import 'reflect-metadata';

@ApiPath({
    path: '/versions',
    name: 'Version',
})
@controller('/versions')
@injectable()
export class VersionController implements interfaces.Controller {
    public static TARGET_NAME: string = 'VersionController';
    private data: [any] = [
        {
            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',
        },
    ];

    @ApiOperationPatch({
        path: '/{id}/description',
        description: 'Patch description in version object',
        summary: 'Patch description in version',
        parameters: {
            path: {
                id: {
                    description: 'Id of version',
                    type: SwaggerDefinitionConstant.Parameter.Type.STRING,
                    required: true,
                },
            },
            body: {
                description: 'New version',
                required: true,
                model: 'Version',
            },
        },
        responses: {
            200: { description: 'Success' },
            400: { description: 'Parameters fail' },
            404: { description: 'Version not found' },
        },
    })
    @httpPatch('/:id/description')
    public patchVersionDescription(
        @requestParam('id') id: string,
        request: express.Request,
        response: express.Response,
        next: express.NextFunction
    ): void {
        if (!request.body) {
            return response.status(400).end();
        }
        this.data.forEach((version: any) => {
            if (version.id === id) {
                version.description = request.body.description;
                return response.json(version);
            }
        });
        response.status(404).end();
    }
}

@ApiOperationPost(args: IApiOperationPostArgs)

Decorate method for create a resource in your controller.

Example:

import * as express from 'express';
import { injectable } from 'inversify';
import {
    controller,
    interfaces,
    requestParam,
    httpPost,
} from 'inversify-express-utils';
import {
    ApiPath,
    ApiOperationPost,
    SwaggerDefinitionConstant,
} from 'swagger-express-ts';
import 'reflect-metadata';

@ApiPath({
    path: '/versions',
    name: 'Version',
})
@controller('/versions')
@injectable()
export class VersionController implements interfaces.Controller {
    public static TARGET_NAME: string = 'VersionController';
    private data: [any] = [
        {
            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',
        },
    ];

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

@ApiOperationPut(args: IApiOperationPutArgs)

Decorate method for updating a resource in your controller.

Example:

import * as express from 'express';
import { injectable } from 'inversify';
import {
    controller,
    interfaces,
    requestParam,
    httpPut,
} from 'inversify-express-utils';
import {
    ApiPath,
    ApiOperationPut,
    SwaggerDefinitionConstant,
} from 'swagger-express-ts';
import 'reflect-metadata';

@ApiPath({
    path: '/versions',
    name: 'Version',
})
@controller('/versions')
@injectable()
export class VersionController implements interfaces.Controller {
    public static TARGET_NAME: string = 'VersionController';
    private data: [any] = [
        {
            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',
        },
    ];

    @ApiOperationPut({
        path: '/{id}',
        parameters: {
            path: {
                id: {
                    description: 'Id of version',
                    type: SwaggerDefinitionConstant.Parameter.Type.STRING,
                    required: true,
                },
            },
            body: {
                description: 'Updated version',
                model: 'Version',
                required: true,
            },
        },
        responses: {
            200: { model: 'Version' },
        },
    })
    @httpPut('/:id')
    public putVersion(
        @requestParam('id') id: string,
        request: express.Request,
        response: express.Response,
        next: express.NextFunction
    ): void {
        if (!request.body) {
            return response.status(400).end();
        }
        this.data.forEach((version: any, index: number) => {
            if (version.id === id) {
                let newVersion = request.body;
                version.id = newVersion.id;
                version.name = newVersion.name;
                version.description = newVersion.description;
                version.version = newVersion.version;
                this.data[index] = version;
                return response.json(version);
            }
        });
        response.status(404).end();
    }
}