{"id":14957585,"url":"https://github.com/olivierlsc/swagger-express-ts","last_synced_at":"2025-12-25T18:53:14.824Z","repository":{"id":40890828,"uuid":"114358491","full_name":"olivierlsc/swagger-express-ts","owner":"olivierlsc","description":"Generate and serve swagger.json","archived":false,"fork":false,"pushed_at":"2023-01-18T03:18:38.000Z","size":2128,"stargazers_count":150,"open_issues_count":45,"forks_count":60,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-28T23:07:19.083Z","etag":null,"topics":["documentation","express","express-js","inversify","inversifyjs","javascript","json","nodejs","rest","rest-api","swagger","swagger2","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/olivierlsc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-12-15T10:26:38.000Z","updated_at":"2025-03-19T13:23:11.000Z","dependencies_parsed_at":"2023-02-10T13:02:51.563Z","dependency_job_id":null,"html_url":"https://github.com/olivierlsc/swagger-express-ts","commit_stats":null,"previous_names":["olivierlsc/swagger-specification-ts"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olivierlsc%2Fswagger-express-ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olivierlsc%2Fswagger-express-ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olivierlsc%2Fswagger-express-ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olivierlsc%2Fswagger-express-ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/olivierlsc","download_url":"https://codeload.github.com/olivierlsc/swagger-express-ts/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247266563,"owners_count":20910836,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","express","express-js","inversify","inversifyjs","javascript","json","nodejs","rest","rest-api","swagger","swagger2","typescript"],"created_at":"2024-09-24T13:15:11.829Z","updated_at":"2025-12-25T18:53:14.767Z","avatar_url":"https://github.com/olivierlsc.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![](wiki/img/logo.png)\n\n# swagger-express-ts\nAutomatically generate and serve swagger.json v2.0.\n\n## Getting started\n\nFirst, install [swagger-express-ts](https://www.npmjs.com/package/swagger-express-ts).\n\n```sh\nnpm install swagger-express-ts --save\n```\n\nand [init tsconfig.json](./wiki/installation.md)\n\n## The Basics\n\nIn the examples below, we use [inversify-express-utils](https://www.npmjs.com/package/inversify-express-utils). inversify-express-utils is not required to work with swagger-express-ts.\n\n### Step 1: configure express\n\n```ts\nimport * as bodyParser from \"body-parser\";\nimport * as express from \"express\";\nimport \"reflect-metadata\";\nimport { Container } from \"inversify\";\nimport { interfaces, InversifyExpressServer, TYPE } from \"inversify-express-utils\";\nimport { VersionController } from \"./version/version.controller\";\nimport * as swagger from \"swagger-express-ts\";\nimport { SwaggerDefinitionConstant } from \"swagger-express-ts\";\nconst config = require ( \"../config.json\" );\n\n// set up container\nconst container = new Container ();\n\n// note that you *must* bind your controllers to Controller\ncontainer.bind\u003cinterfaces.Controller\u003e ( TYPE.Controller )\n    .to( VersionController ).inSingletonScope().whenTargetNamed( VersionController.TARGET_NAME );\n\n// create server\nconst server = new InversifyExpressServer ( container );\n\nserver.setConfig( ( app : any ) =\u003e {\n    app.use( '/api-docs/swagger' , express.static( 'swagger' ) );\n    app.use( '/api-docs/swagger/assets' , express.static( 'node_modules/swagger-ui-dist' ) );\n    app.use( bodyParser.json() );\n    app.use( swagger.express(\n        {\n            definition : {\n                info : {\n                    title : \"My api\" ,\n                    version : \"1.0\"\n                } ,\n                externalDocs : {\n                    url : \"My url\"\n                }\n                // Models can be defined here\n            }\n        }\n    ) );\n} );\n\nserver.setErrorConfig( ( app : any ) =\u003e {\n    app.use( ( err : Error , request : express.Request , response : express.Response , next : express.NextFunction ) =\u003e {\n        console.error( err.stack );\n        response.status( 500 ).send( \"Something broke!\" );\n    } );\n} );\n\nconst app = server.build();\n\napp.listen( config.port );\nconsole.info( \"Server is listening on port : \" + config.port );\n\n```\n\n### Step 2: Decorate your models\n\n```ts\n@ApiModel( {\n    description : \"Version description\" ,\n    name : \"Version\"\n} )\nexport class VersionModel {\n\n    @ApiModelProperty( {\n        description : \"Id of version\" ,\n        required : true,\n        example: ['123456789']\n    } )\n    id : number;\n\n    @ApiModelProperty( {\n        description : \"\" ,\n        required : true\n    } )\n    name : string;\n\n    @ApiModelProperty( {\n        description : \"Description of version\" ,\n        required : true\n    } )\n    description : string;\n}\n```\n\n### Step 3: Decorate your controllers\n\n```ts\n@ApiPath({\n    path: \"/versions\",\n    name: \"Version\",\n    security: { basicAuth: [] }\n})\n@controller(\"/versions\")\n@injectable()\nexport class VersionController implements interfaces.Controller {\n    public static TARGET_NAME: string = \"VersionController\";\n    \n    private data = [{\n            id: \"1\",\n            name: \"Version 1\",\n            description: \"Description Version 1\",\n            version: \"1.0.0\"\n        },\n        {\n            id: \"2\",\n            name: \"Version 2\",\n            description: \"Description Version 2\",\n            version: \"2.0.0\"\n        }];\n\n    @ApiOperationGet({\n        description: \"Get versions objects list\",\n        summary: \"Get versions list\",\n        responses: {\n            200: { description: \"Success\", type: SwaggerDefinitionConstant.Response.Type.ARRAY, model: \"Version\" }\n        },\n        security: {\n            apiKeyHeader: []\n        }\n    })\n    @httpGet(\"/\")\n    public getVersions(request: express.Request, response: express.Response, next: express.NextFunction): void {\n        response.json(this.data);\n    }\n\n    @ApiOperationPost({\n        description: \"Post version object\",\n        summary: \"Post new version\",\n        parameters: {\n            body: { description: \"New version\", required: true, model: \"Version\" }\n        },\n        responses: {\n            200: { description: \"Success\" },\n            400: { description: \"Parameters fail\" }\n        }\n    })\n    @httpPost(\"/\")\n    public postVersion(request: express.Request, response: express.Response, next: express.NextFunction): void {\n        if (!request.body) {\n            return response.status(400).end();\n        }\n        this.data.push(request.body);\n        response.json(request.body);\n    }\n\n}\n```\n\n### Step 4: Test\n\nStart your server and test on url : /api-docs/swagger.json\n\n## Extra\n\n### Serve swagger-ui in your API\n\nYou can serve swagger.json and swagger-ui in your API.\n\n```sh\nnpm install swagger-ui-dist --save\n```\n\nCreate index.html in new directory \"swagger\".\n\n```html\n\u003c!-- HTML for static distribution bundle build --\u003e\n\u003c!DOCTYPE html\u003e\n\u003chtml lang=\"en\"\u003e\n\u003chead\u003e\n    \u003cmeta charset=\"UTF-8\"\u003e\n    \u003ctitle\u003eSwagger UI\u003c/title\u003e\n    \u003clink href=\"https://fonts.googleapis.com/css?family=Open+Sans:400,700|Source+Code+Pro:300,600|Titillium+Web:400,600,700\"\n          rel=\"stylesheet\"\u003e\n    \u003clink rel=\"stylesheet\" type=\"text/css\" href=\"/api-docs/swagger/assets/swagger-ui.css\"\u003e\n    \u003clink rel=\"icon\" type=\"image/png\" href=\"/api-docs/swagger/assets/favicon-32x32.png\" sizes=\"32x32\"/\u003e\n    \u003clink rel=\"icon\" type=\"image/png\" href=\"/api-docs/swagger/assets/favicon-16x16.png\" sizes=\"16x16\"/\u003e\n    \u003cstyle\u003e\n        html {\n            box-sizing: border-box;\n            overflow: -moz-scrollbars-vertical;\n            overflow-y: scroll;\n        }\n\n        *,\n        *:before,\n        *:after {\n            box-sizing: inherit;\n        }\n\n        body {\n            margin: 0;\n            background: #fafafa;\n        }\n    \u003c/style\u003e\n\u003c/head\u003e\n\n\u003cbody\u003e\n\n\u003csvg xmlns=\"http://www.w3.org/2000/svg\" xmlns:xlink=\"http://www.w3.org/1999/xlink\"\n     style=\"position:absolute;width:0;height:0\"\u003e\n    \u003cdefs\u003e\n        \u003csymbol viewBox=\"0 0 20 20\" id=\"unlocked\"\u003e\n            \u003cpath d=\"M15.8 8H14V5.6C14 2.703 12.665 1 10 1 7.334 1 6 2.703 6 5.6V6h2v-.801C8 3.754 8.797 3 10 3c1.203 0 2 .754 2 2.199V8H4c-.553 0-1 .646-1 1.199V17c0 .549.428 1.139.951 1.307l1.197.387C5.672 18.861 6.55 19 7.1 19h5.8c.549 0 1.428-.139 1.951-.307l1.196-.387c.524-.167.953-.757.953-1.306V9.199C17 8.646 16.352 8 15.8 8z\"\u003e\u003c/path\u003e\n        \u003c/symbol\u003e\n\n        \u003csymbol viewBox=\"0 0 20 20\" id=\"locked\"\u003e\n            \u003cpath d=\"M15.8 8H14V5.6C14 2.703 12.665 1 10 1 7.334 1 6 2.703 6 5.6V8H4c-.553 0-1 .646-1 1.199V17c0 .549.428 1.139.951 1.307l1.197.387C5.672 18.861 6.55 19 7.1 19h5.8c.549 0 1.428-.139 1.951-.307l1.196-.387c.524-.167.953-.757.953-1.306V9.199C17 8.646 16.352 8 15.8 8zM12 8H8V5.199C8 3.754 8.797 3 10 3c1.203 0 2 .754 2 2.199V8z\"/\u003e\n        \u003c/symbol\u003e\n\n        \u003csymbol viewBox=\"0 0 20 20\" id=\"close\"\u003e\n            \u003cpath d=\"M14.348 14.849c-.469.469-1.229.469-1.697 0L10 11.819l-2.651 3.029c-.469.469-1.229.469-1.697 0-.469-.469-.469-1.229 0-1.697l2.758-3.15-2.759-3.152c-.469-.469-.469-1.228 0-1.697.469-.469 1.228-.469 1.697 0L10 8.183l2.651-3.031c.469-.469 1.228-.469 1.697 0 .469.469.469 1.229 0 1.697l-2.758 3.152 2.758 3.15c.469.469.469 1.229 0 1.698z\"/\u003e\n        \u003c/symbol\u003e\n\n        \u003csymbol viewBox=\"0 0 20 20\" id=\"large-arrow\"\u003e\n            \u003cpath d=\"M13.25 10L6.109 2.58c-.268-.27-.268-.707 0-.979.268-.27.701-.27.969 0l7.83 7.908c.268.271.268.709 0 .979l-7.83 7.908c-.268.271-.701.27-.969 0-.268-.269-.268-.707 0-.979L13.25 10z\"/\u003e\n        \u003c/symbol\u003e\n\n        \u003csymbol viewBox=\"0 0 20 20\" id=\"large-arrow-down\"\u003e\n            \u003cpath d=\"M17.418 6.109c.272-.268.709-.268.979 0s.271.701 0 .969l-7.908 7.83c-.27.268-.707.268-.979 0l-7.908-7.83c-.27-.268-.27-.701 0-.969.271-.268.709-.268.979 0L10 13.25l7.418-7.141z\"/\u003e\n        \u003c/symbol\u003e\n\n\n        \u003csymbol viewBox=\"0 0 24 24\" id=\"jump-to\"\u003e\n            \u003cpath d=\"M19 7v4H5.83l3.58-3.59L8 6l-6 6 6 6 1.41-1.41L5.83 13H21V7z\"/\u003e\n        \u003c/symbol\u003e\n\n        \u003csymbol viewBox=\"0 0 24 24\" id=\"expand\"\u003e\n            \u003cpath d=\"M10 18h4v-2h-4v2zM3 6v2h18V6H3zm3 7h12v-2H6v2z\"/\u003e\n        \u003c/symbol\u003e\n\n    \u003c/defs\u003e\n\u003c/svg\u003e\n\n\u003cdiv id=\"swagger-ui\"\u003e\u003c/div\u003e\n\n\u003cscript src=\"/api-docs/swagger/assets/swagger-ui-bundle.js\"\u003e\u003c/script\u003e\n\u003cscript src=\"/api-docs/swagger/assets/swagger-ui-standalone-preset.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n    window.onload = function () {\n\n        // Build a system\n        const ui = SwaggerUIBundle ({\n            url: \"/api-docs/swagger.json\",\n            dom_id: '#swagger-ui',\n            deepLinking: true,\n            presets: [\n                SwaggerUIBundle.presets.apis,\n                SwaggerUIStandalonePreset\n            ],\n            plugins: [\n                SwaggerUIBundle.plugins.DownloadUrl\n            ],\n            layout: \"StandaloneLayout\",\n            validatorUrl: null\n        });\n\n        window.ui = ui\n    }\n\u003c/script\u003e\n\u003c/body\u003e\n\n\u003c/html\u003e\n\n```\n\nConfigure your server like that.\n\n```ts\napp.use( '/api-docs/swagger', express.static( 'swagger' ) );\napp.use( '/api-docs/swagger/assets', express.static( 'node_modules/swagger-ui-dist' ) );\n```\n\nTest it on url \"/api-docs/swagger\".\n\n![](./wiki/img/swagger-ui.png)\n\n## Project example\n\nYou can quickly test swagger-express-ts with the project example [example-swagger-express-ts](https://github.com/olivierlsc/example-swagger-express-ts).\n\n## Features and API\n\n- [Installation](./wiki/installation.md)\n- [Configuration](./wiki/configuration.md)\n- [@ApiModel](./wiki/api-model.decorator.md)\n- [@ApiModelProperty](./wiki/api-model-property.decorator.md)\n- [@ApiPath](./wiki/api-path.decorator.md)\n- [@ApiOperationGet](./wiki/api-operation-get.decorator.md)\n- [@ApiOperationPost](./wiki/api-operation-post.decorator.md)\n- [@ApiOperationPut](./wiki/api-operation-put.decorator.md)\n- [@ApiOperationPatch](./wiki/api-operation-patch.decorator.md)\n- [@ApiOperationDelete](./wiki/api-operation-delete.decorator.md)\n\n## For any questions, suggestions, or feature requests\n\n[Please file an issue](https://github.com/olivierlsc/swagger-express-ts/issues)!\n\n## Help wanted\n\nswagger-express-ts wants additional maintainers! To maintain and continue to develop this young library, [Please post in this issue](https://github.com/olivierlsc/swagger-express-ts/issues/34).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Folivierlsc%2Fswagger-express-ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Folivierlsc%2Fswagger-express-ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Folivierlsc%2Fswagger-express-ts/lists"}