├── .gitignore ├── LICENSE ├── README.md ├── package.json ├── src ├── controllers │ ├── ApiRoute1.js │ ├── ApiRoute2.js │ └── ToolsController.js ├── index.js ├── middlewares │ └── auth.js └── routes.js ├── swagger-output.json └── swagger.js /.gitignore: -------------------------------------------------------------------------------- 1 | # Logs 2 | logs 3 | *.log 4 | npm-debug.log* 5 | yarn-debug.log* 6 | yarn-error.log* 7 | lerna-debug.log* 8 | 9 | # Diagnostic reports (https://nodejs.org/api/report.html) 10 | report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json 11 | 12 | # Runtime data 13 | pids 14 | *.pid 15 | *.seed 16 | *.pid.lock 17 | 18 | # Directory for instrumented libs generated by jscoverage/JSCover 19 | lib-cov 20 | 21 | # Coverage directory used by tools like istanbul 22 | coverage 23 | *.lcov 24 | 25 | # nyc test coverage 26 | .nyc_output 27 | 28 | # Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files) 29 | .grunt 30 | 31 | # Bower dependency directory (https://bower.io/) 32 | bower_components 33 | 34 | # node-waf configuration 35 | .lock-wscript 36 | 37 | # Compiled binary addons (https://nodejs.org/api/addons.html) 38 | build/Release 39 | 40 | # Dependency directories 41 | node_modules/ 42 | jspm_packages/ 43 | 44 | # TypeScript v1 declaration files 45 | typings/ 46 | 47 | # TypeScript cache 48 | *.tsbuildinfo 49 | 50 | # Optional npm cache directory 51 | .npm 52 | 53 | # Optional eslint cache 54 | .eslintcache 55 | 56 | # Microbundle cache 57 | .rpt2_cache/ 58 | .rts2_cache_cjs/ 59 | .rts2_cache_es/ 60 | .rts2_cache_umd/ 61 | 62 | # Optional REPL history 63 | .node_repl_history 64 | 65 | # Output of 'npm pack' 66 | *.tgz 67 | 68 | # Yarn Integrity file 69 | .yarn-integrity 70 | 71 | # dotenv environment variables file 72 | .env 73 | .env.test 74 | 75 | # parcel-bundler cache (https://parceljs.org/) 76 | .cache 77 | 78 | # Next.js build output 79 | .next 80 | 81 | # Nuxt.js build / generate output 82 | .nuxt 83 | dist 84 | 85 | # Gatsby files 86 | .cache/ 87 | # Comment in the public line in if your project uses Gatsby and *not* Next.js 88 | # https://nextjs.org/blog/next-9-1#public-directory-support 89 | # public 90 | 91 | # vuepress build output 92 | .vuepress/dist 93 | 94 | # Serverless directories 95 | .serverless/ 96 | 97 | # FuseBox cache 98 | .fusebox/ 99 | 100 | # DynamoDB Local files 101 | .dynamodb/ 102 | 103 | # TernJS port file 104 | .tern-port 105 | .DS_Store 106 | package-lock.json 107 | test/*.json 108 | .vscode/launch.json -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2020 davibaltar 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # example-swagger-autogen-using-router 2 | 3 | Install the dependencies: 4 | 5 | ```bash 6 | $ npm install 7 | ``` 8 | 9 | Use the command below to generate the documentation at project startup: 10 | 11 | ```bash 12 | $ npm run start-gendoc 13 | ``` 14 | 15 | Use the command below to start the project without generating the documentation: 16 | 17 | ```bash 18 | $ npm start 19 | ``` 20 | 21 | Run the project and access the documentation at: 22 | 23 | [http://localhost:3000/doc](http://localhost:3000/doc) 24 | 25 | ## Screenshot 26 | See the result after construction: 27 | 28 | ![](https://raw.githubusercontent.com/davibaltar/public-store/master/screen-swagger-autogen-using-router.png) 29 | 30 | 31 | ## License 32 | [MIT](LICENSE) License -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "example-swagger-autogen-using-router", 3 | "version": "1.0.0", 4 | "description": "Example showing the use of the swagger-autogen module with Router.", 5 | "main": "index.js", 6 | "readmeFilename": "README.md", 7 | "private": false, 8 | "keywords": [ 9 | "swagger", 10 | "autogen", 11 | "example", 12 | "router" 13 | ], 14 | "author": { 15 | "name": "Davi D. Baltar", 16 | "email": "davibaltar.npm@gmail.com" 17 | }, 18 | "license": "MIT", 19 | "repository": { 20 | "type": "git", 21 | "url": "git+https://github.com/davibaltar/example-swagger-autogen-with-router.git" 22 | }, 23 | "scripts": { 24 | "start": "node src/index.js", 25 | "start-gendoc": "node swagger.js" 26 | }, 27 | "dependencies": { 28 | "express": "^4.17.1", 29 | "swagger-autogen": "^2.23.4", 30 | "swagger-ui-express": "^4.1.4" 31 | } 32 | } 33 | -------------------------------------------------------------------------------- /src/controllers/ApiRoute1.js: -------------------------------------------------------------------------------- 1 | const express = require('express') 2 | const router = express.Router() 3 | const authorize = require('../middlewares/auth') 4 | 5 | router.post('/signin', (req, res, next) => { 6 | /* #swagger.tags = ['User'] 7 | #swagger.description = 'Endpoint to sign in a specific user' */ 8 | 9 | /* #swagger.parameters['obj'] = { 10 | in: 'body', 11 | description: 'User information.', 12 | required: true, 13 | schema: { $ref: "#/definitions/AddUser" } 14 | } */ 15 | 16 | /* #swagger.security = [{ 17 | "apiKeyAuth": [] 18 | }] */ 19 | res.status(201).json({ 20 | data: [], 21 | message: 'Authentication successed' 22 | }) 23 | }) 24 | 25 | router.route('/users/:id').get(authorize, (req, res) => { 26 | // #swagger.tags = ['User'] 27 | // #swagger.description = 'Endpoint to get a specific user.' 28 | const users = [] 29 | const data = users.find(e => e.id === req.params.id) 30 | 31 | /* #swagger.responses[200] = { 32 | schema: { "$ref": "#/definitions/User" }, 33 | description: "User registered successfully." } */ 34 | res.status(200).json({ 35 | data: [], 36 | message: 'Successfully found' 37 | }) 38 | }) 39 | 40 | module.exports = router -------------------------------------------------------------------------------- /src/controllers/ApiRoute2.js: -------------------------------------------------------------------------------- 1 | const express = require('express') 2 | 3 | const router = express.Router() 4 | const authorize = require('../middlewares/auth') 5 | 6 | router.route('/test-get').get(authorize, (req, res, next) => { 7 | // #swagger.description = "Description here..." 8 | res.status(200).json({ 9 | data: [], 10 | message: 'Successfully found' 11 | }) 12 | }) 13 | 14 | router.route('/test-delete/:id').delete(authorize, async (req, res, next) => { 15 | res.status(200).json({ 16 | msg: [], 17 | message: 'Delete!' 18 | }) 19 | }) 20 | 21 | module.exports = router -------------------------------------------------------------------------------- /src/controllers/ToolsController.js: -------------------------------------------------------------------------------- 1 | 2 | module.exports = { 3 | 4 | async show(req, res) { 5 | res.setHeader('Content-Type', 'application/json') 6 | return res.status(200).send(true) 7 | }, 8 | 9 | async delete(req, res) { 10 | return res.status(204).send("delete") 11 | } 12 | } -------------------------------------------------------------------------------- /src/index.js: -------------------------------------------------------------------------------- 1 | /* 2 | * Run the project and access the documentation at: http://localhost:3000/doc 3 | * 4 | * Use the command below to generate the documentation without starting the project: 5 | * $ npm start 6 | * 7 | * Use the command below to generate the documentation at project startup: 8 | * $ npm run start-gendoc 9 | */ 10 | 11 | 12 | const swaggerUi = require('swagger-ui-express') 13 | const swaggerFile = require('../swagger-output.json') 14 | const express = require('express') 15 | const app = express() 16 | 17 | /* Routes */ 18 | const router = require('./routes') 19 | 20 | /* Middlewares */ 21 | app.use(router) 22 | app.use('/doc', swaggerUi.serve, swaggerUi.setup(swaggerFile)) 23 | 24 | app.listen(3000, () => { 25 | console.log("Server is running!\nAPI documentation: http://localhost:3000/doc") 26 | }) 27 | -------------------------------------------------------------------------------- /src/middlewares/auth.js: -------------------------------------------------------------------------------- 1 | 2 | module.exports = (req, res, next) => { 3 | try { 4 | // validation... 5 | next() 6 | } catch (error) { 7 | res.status(401).json({ message: "Authentication failed!" }) 8 | } 9 | } -------------------------------------------------------------------------------- /src/routes.js: -------------------------------------------------------------------------------- 1 | 2 | const express = require('express') 3 | const ToolsController = require('./controllers/ToolsController') 4 | 5 | const router = express.Router() 6 | 7 | const apiV1 = require('./controllers/ApiRoute1') 8 | const apiV2 = require('./controllers/ApiRoute2') 9 | 10 | router.use(apiV1) 11 | router.use('/v2', apiV2) 12 | 13 | router.get('/test-get', ToolsController.show) 14 | router.post('/test-post', store) 15 | router.delete('/test-delete/:id', ToolsController.delete) 16 | 17 | function store(req, res) { 18 | const tools = {} 19 | return res.status(201).send({}) 20 | } 21 | 22 | module.exports = router -------------------------------------------------------------------------------- /swagger-output.json: -------------------------------------------------------------------------------- 1 | { 2 | "swagger": "2.0", 3 | "info": { 4 | "version": "1.0.0", 5 | "title": "My API", 6 | "description": "Documentation automatically generated by the swagger-autogen module." 7 | }, 8 | "host": "localhost:3000", 9 | "basePath": "/", 10 | "tags": [ 11 | { 12 | "name": "User", 13 | "description": "Endpoints" 14 | } 15 | ], 16 | "schemes": [ 17 | "http", 18 | "https" 19 | ], 20 | "securityDefinitions": { 21 | "apiKeyAuth": { 22 | "type": "apiKey", 23 | "in": "header", 24 | "name": "X-API-KEY", 25 | "description": "any description..." 26 | } 27 | }, 28 | "consumes": [ 29 | "application/json" 30 | ], 31 | "produces": [ 32 | "application/json" 33 | ], 34 | "paths": { 35 | "/test-get": { 36 | "get": { 37 | "tags": [], 38 | "description": "", 39 | "produces": [ 40 | "application/json" 41 | ], 42 | "parameters": [], 43 | "responses": { 44 | "200": { 45 | "description": "OK" 46 | } 47 | } 48 | } 49 | }, 50 | "/test-post": { 51 | "post": { 52 | "tags": [], 53 | "description": "", 54 | "parameters": [], 55 | "responses": { 56 | "201": { 57 | "description": "Created" 58 | } 59 | } 60 | } 61 | }, 62 | "/test-delete/{id}": { 63 | "delete": { 64 | "tags": [], 65 | "description": "", 66 | "parameters": [ 67 | { 68 | "name": "id", 69 | "in": "path", 70 | "required": true, 71 | "type": "string" 72 | } 73 | ], 74 | "responses": { 75 | "204": { 76 | "description": "No Content" 77 | } 78 | } 79 | } 80 | }, 81 | "/signin": { 82 | "post": { 83 | "tags": [ 84 | "User" 85 | ], 86 | "description": "Endpoint to sign in a specific user", 87 | "parameters": [ 88 | { 89 | "name": "obj", 90 | "in": "body", 91 | "description": "User information.", 92 | "required": true, 93 | "schema": { 94 | "$ref": "#/definitions/AddUser" 95 | } 96 | } 97 | ], 98 | "responses": { 99 | "201": { 100 | "description": "Created" 101 | } 102 | }, 103 | "security": [ 104 | { 105 | "apiKeyAuth": [] 106 | } 107 | ] 108 | } 109 | }, 110 | "/users/{id}": { 111 | "get": { 112 | "tags": [ 113 | "User" 114 | ], 115 | "description": "Endpoint to get a specific user.", 116 | "parameters": [ 117 | { 118 | "name": "id", 119 | "in": "path", 120 | "required": true, 121 | "type": "string" 122 | } 123 | ], 124 | "responses": { 125 | "200": { 126 | "description": "User registered successfully.", 127 | "schema": { 128 | "$ref": "#/definitions/User" 129 | } 130 | }, 131 | "401": { 132 | "description": "Unauthorized" 133 | } 134 | } 135 | } 136 | }, 137 | "/v2/test-get": { 138 | "get": { 139 | "tags": [], 140 | "description": "Description here...", 141 | "parameters": [], 142 | "responses": { 143 | "200": { 144 | "description": "OK" 145 | }, 146 | "401": { 147 | "description": "Unauthorized" 148 | } 149 | } 150 | } 151 | }, 152 | "/v2/test-delete/{id}": { 153 | "delete": { 154 | "tags": [], 155 | "description": "", 156 | "parameters": [ 157 | { 158 | "name": "id", 159 | "in": "path", 160 | "required": true, 161 | "type": "string" 162 | } 163 | ], 164 | "responses": { 165 | "200": { 166 | "description": "OK" 167 | }, 168 | "401": { 169 | "description": "Unauthorized" 170 | } 171 | } 172 | } 173 | } 174 | }, 175 | "definitions": { 176 | "Parents": { 177 | "type": "object", 178 | "properties": { 179 | "father": { 180 | "type": "string", 181 | "example": "Simon Doe" 182 | }, 183 | "mother": { 184 | "type": "string", 185 | "example": "Marie Doe" 186 | } 187 | } 188 | }, 189 | "User": { 190 | "type": "object", 191 | "properties": { 192 | "name": { 193 | "type": "string", 194 | "example": "Jhon Doe" 195 | }, 196 | "age": { 197 | "type": "number", 198 | "example": 29 199 | }, 200 | "parents": { 201 | "$ref": "#/definitions/Parents" 202 | }, 203 | "diplomas": { 204 | "type": "array", 205 | "items": { 206 | "type": "object", 207 | "properties": { 208 | "school": { 209 | "type": "string", 210 | "example": "XYZ University" 211 | }, 212 | "year": { 213 | "type": "number", 214 | "example": 2020 215 | }, 216 | "completed": { 217 | "type": "boolean", 218 | "example": true 219 | }, 220 | "internship": { 221 | "type": "object", 222 | "properties": { 223 | "hours": { 224 | "type": "number", 225 | "example": 290 226 | }, 227 | "location": { 228 | "type": "string", 229 | "example": "XYZ Company" 230 | } 231 | } 232 | } 233 | } 234 | } 235 | } 236 | } 237 | }, 238 | "AddUser": { 239 | "type": "object", 240 | "properties": { 241 | "name": { 242 | "type": "string", 243 | "example": "Jhon Doe" 244 | }, 245 | "age": { 246 | "type": "number", 247 | "example": 29 248 | }, 249 | "about": { 250 | "type": "string", 251 | "example": "" 252 | } 253 | }, 254 | "required": [ 255 | "name", 256 | "age" 257 | ] 258 | } 259 | } 260 | } 261 | -------------------------------------------------------------------------------- /swagger.js: -------------------------------------------------------------------------------- 1 | const swaggerAutogen = require('swagger-autogen')() 2 | 3 | 4 | const doc = { 5 | info: { 6 | version: "1.0.0", 7 | title: "My API", 8 | description: "Documentation automatically generated by the swagger-autogen module." 9 | }, 10 | host: "localhost:3000", 11 | basePath: "/", 12 | schemes: ['http', 'https'], 13 | consumes: ['application/json'], 14 | produces: ['application/json'], 15 | tags: [ 16 | { 17 | "name": "User", 18 | "description": "Endpoints" 19 | } 20 | ], 21 | securityDefinitions: { 22 | apiKeyAuth:{ 23 | type: "apiKey", 24 | in: "header", // can be "header", "query" or "cookie" 25 | name: "X-API-KEY", // name of the header, query parameter or cookie 26 | description: "any description..." 27 | } 28 | }, 29 | definitions: { 30 | Parents: { 31 | father: "Simon Doe", 32 | mother: "Marie Doe" 33 | }, 34 | User: { 35 | name: "Jhon Doe", 36 | age: 29, 37 | parents: { 38 | $ref: '#/definitions/Parents' 39 | }, 40 | diplomas: [ 41 | { 42 | school: "XYZ University", 43 | year: 2020, 44 | completed: true, 45 | internship: { 46 | hours: 290, 47 | location: "XYZ Company" 48 | } 49 | } 50 | ] 51 | }, 52 | AddUser: { 53 | $name: "Jhon Doe", 54 | $age: 29, 55 | about: "" 56 | } 57 | } 58 | } 59 | 60 | const outputFile = './swagger-output.json' 61 | const endpointsFiles = ['./src/index.js'] 62 | 63 | swaggerAutogen(outputFile, endpointsFiles, doc).then(() => { 64 | require('./src/index') // Your project's root file 65 | }) --------------------------------------------------------------------------------