{"id":21952009,"url":"https://github.com/systangotechnologies/swagger-generator-express","last_synced_at":"2026-02-25T21:03:46.120Z","repository":{"id":35088065,"uuid":"204639964","full_name":"SystangoTechnologies/swagger-generator-express","owner":"SystangoTechnologies","description":"Swagger generator for Express App","archived":false,"fork":false,"pushed_at":"2022-12-11T03:25:35.000Z","size":136,"stargazers_count":23,"open_issues_count":11,"forks_count":7,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-23T04:03:41.446Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SystangoTechnologies.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-08-27T06:55:21.000Z","updated_at":"2025-04-14T09:21:59.000Z","dependencies_parsed_at":"2023-01-15T13:35:12.175Z","dependency_job_id":null,"html_url":"https://github.com/SystangoTechnologies/swagger-generator-express","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SystangoTechnologies%2Fswagger-generator-express","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SystangoTechnologies%2Fswagger-generator-express/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SystangoTechnologies%2Fswagger-generator-express/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SystangoTechnologies%2Fswagger-generator-express/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SystangoTechnologies","download_url":"https://codeload.github.com/SystangoTechnologies/swagger-generator-express/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250366710,"owners_count":21418770,"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":[],"created_at":"2024-11-29T06:19:06.861Z","updated_at":"2026-02-25T21:03:41.097Z","avatar_url":"https://github.com/SystangoTechnologies.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# swagger-generator-express\n\nNPM module to generate swagger documentation for Express APIs with minimum additional effort.\n\n\u003e[![Downloads](https://badgen.net/npm/dt/swagger-generator-express)](https://www.npmjs.com/package/swagger-generator-express) [![npm dependents](https://badgen.net/npm/dependents/swagger-generator-express)](https://www.npmjs.com/package/swagger-generator-express?activeTab=dependents)\n\n## Description\nThis NPM module let's you validate and generate swagger (OpenAPI) documentation for your Express APIs without putting in much extra efforts. You just need to follow the convention for your request and response objects, and the module will take care of the rest. This module will cover your controllers, API specs along with request and response object structures.\n\n\n## Usage ##\n\nInstall using npm:\n\n```bash\n$ npm install --save swagger-generator-express\n```\n\n### Express setup `app.js` ###\n\n```javascript\nconst express = require(\"express\");\nconst app = express();\nconst swagger = require(\"swagger-generator-express\");\n\n// Define your router here\n\nconst options = {\n\ttitle: \"swagger-generator-express\",\n\tversion: \"1.0.0\",\n\thost: \"localhost:3000\",\n\tbasePath: \"/\",\n\tschemes: [\"http\", \"https\"],\n\tsecurityDefinitions: {\n\t\tBearer: {\n\t\t\tdescription: 'Example value:- Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjU5MmQwMGJhNTJjYjJjM',\n\t\t\ttype: 'apiKey',\n\t\t\tname: 'Authorization',\n\t\t\tin: 'header'\n\t\t}\n\t},\n\tsecurity: [{Bearer: []}],\n\tdefaultSecurity: 'Bearer'\n};\n\n/**\n * serveSwagger must be called after defining your router.\n * @param app Express object\n * @param endPoint Swagger path on which swagger UI display\n * @param options Swagget Options.\n * @param path.routePath path to folder in which routes files defined.\n * @param path.requestModelPath Optional parameter which is path to folder in which requestModel defined, if not given request params will not display on swagger documentation.\n * @param path.responseModelPath Optional parameter which is path to folder in which responseModel defined, if not given response objects will not display on swagger documentation.\n */\nswagger.serveSwagger(app, \"/swagger\", options, {routePath : './src/routes/', requestModelPath: './src/requestModel', responseModelPath: './src/responseModel'});\n\n```\n\n### Express router `user.js` ###\n\n```javascript\n'use strict';\nvar express = require('express');\nvar router = express.Router();\nvar { validation } = require('swagger-generator-express');\nvar userController = require('../controller/user');\nvar requestModel = require('../requestModel/users');\n\nrouter.post('/', validation(requestModel[0]), userController.createUser);\n\nrouter.get('/', userController.getUsers);\n\nrouter.put('/:userId', userController.updateUser);\n\nrouter.get('/:userId', userController.getUserDetails);\n\nrouter.delete('/:userId', userController.deleteUser);\n\nmodule.exports = router;\n/**\n *  Router can be exported in different ways if your structure need export some other data along with routers. \n * Create object with key router inside and export from there For example\n * module.exports = {\n        router: router,\n        basePath: '/users'\n    }\n * /\n\n```\n\n## Request Model `/requestModel/user.js`\n  - File name for request model should be same as router file.\n  - Define request model with their order of apis in router js file. For example first api in user router is create user so you need to define createUser schema with key 0.\n  - Add boolean flag \"excludeFromSwagger\" inside requestmodel if you want to exclude any particular api from swagger documentation.\n  - This Request model follows Joi module conventions, so it can also be used for request parameters validation.\n\n```javascript\nconst Joi = require(\"@hapi/joi\");\n/**\n * File name for request and response model should be same as router file.\n * Define request model with there order in router js file.\n * For example first api in user router is create user so we define createUser schema with key 0.\n */\nmodule.exports = {\n    // Here 0 is the order of api in route file.\n    0: {\n        body: {\n            firstName: Joi.string().required(),\n            lastName: Joi.string().required(),\n            address: Joi.string().required(),\n            contact: Joi.number().required()\n        },\n        model: \"createUser\", // Name of the model\n        group: \"User\", // Swagger tag for apis.\n        description: \"Create user and save details in database\"\n    },\n    1: {\n        query: {},\n        path: {}, // Define for api path param here.\n        header: {}, // Define if header required.\n        group: \"User\",\n        description: \"Get All User\"\n    },\n    2: {\n        body: {\n            firstName: Joi.string().required(),\n            lastName: Joi.string().required(),\n            address: Joi.string().required(),\n            contact: Joi.number().required()\n        },\n        model: \"updateUser\",\n        group: \"User\",\n        description: \"Update User\"\n    },\n    3: {\n        query: {},\n        path: {\n            userId: Joi.number().required()\n        }, // Define for api path param here.\n        header: {}, // Define if header required.\n        model: 'getUserDetails',\n        group: \"User\",\n        description: \"Get user details\"\n    },\n    4: {\n        excludeFromSwagger: false // Make it true if need to exclude apis from swagger.\n    }\n};\n```\n\n## Response Model `/responseModel/user.js`\n\n - File name for response model should be same as router file.\n - Response name should be same as model name from requestmodel. For example model name of create user api is \"createUser\" so key for response object will be \"createUser\".\n - Inside response model define responses with respect to their status code returned from apis.\n\n```javascript\n\n// The name of each response payload should be model name defined in Request model schema.\n\n// The name of each response payload should be  model name defined in Request model schema and should sufix with ResponseModel.\n\nmodule.exports = {\n    createUser: {\n        201: {\n            message: {\n                type: 'string'\n            }\n        },\n        500: {\n            internal: {\n                type: 'string'\n            }\n        }\n    },\n    getUsers: {\n        200: [{\n            id: {\n                type: 'number'\n            },\n            firstName: {\n                type: 'string',\n                pattern: '^\\d{3}-\\d{2}-\\d{4}$'\n            },\n            lastName: {\n                type: 'string'\n            },\n            address: {\n                type: 'string'\n            },\n            contact: {\n                type: 'number'\n            },\n            createdAt: {\n                type: 'string',\n                format: 'date-time'\n            },\n            updatedAt: {\n                type: 'string',\n                format: 'date-time'\n            }\n        }],\n        500: {\n            internal: \"string\"\n        }\n    },\n    updateUser: {\n        201: {\n            message: {\n                type: 'string'\n            }\n        },\n        500: {\n            internal: {\n                type: 'string'\n            }\n        }\n    },\n    getUserDetails: {\n        200: {\n            id: {\n                type: 'number'\n            },\n            firstName: {\n                type: 'string',\n                pattern: '^\\d{3}-\\d{2}-\\d{4}$'\n            },\n            lastName: {\n                type: 'string'\n            },\n            address: {\n                type: 'string'\n            },\n            contact: {\n                type: 'number'\n            },\n            createdAt: {\n                type: 'string',\n                format: 'date-time'\n            },\n            updatedAt: {\n                type: 'string',\n                format: 'date-time'\n            }\n        },\n        500: {\n            internal: {\n                type: 'string'\n            }\n        }\n    },\n};\n```\n\nOpen `http://`\u003capp_host\u003e`:`\u003capp_port\u003e`/swagger` in your browser to view the documentation.\n\n# Version changes\n\n## v2.1.0\n\n#### Added Request Parameter Validation Function\n\n- Use `validation` function exported from this module to validate request params.\n\n```javascript\n'use strict';\nvar express = require('express');\nvar router = express.Router();\nvar { validation } = require('swagger-generator-express');\nvar userController = require('../controller/user');\nvar requestModel = require('../requestModel/users');\n\n/**\n * Function: validation\n * Use validation function to validate request parameter.\n * @param schema Joi schema for request.\n */\nrouter.post('/', validation(requestModel[0]), userController.createUser);\n\nmodule.exports = router;\n```\n\n\n## Pre-requisite\n\n- Node v10 or above\n- Express 4 or above\n\n## Contributors\n\n[Vikas Patidar](https://www.linkedin.com/in/vikas-patidar-0106/)\n[Nidhi Tripathi](https://www.linkedin.com/in/nidhi-tripathi-3244817a/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsystangotechnologies%2Fswagger-generator-express","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsystangotechnologies%2Fswagger-generator-express","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsystangotechnologies%2Fswagger-generator-express/lists"}