├── .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 | 
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 | })
--------------------------------------------------------------------------------