├── .gitignore ├── README.md ├── package.json ├── swagger.js ├── configuration └── swagger.js └── docs ├── user.yaml └── pet.yaml /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # swagger-docs-tutorial 2 | A tutorial for creating swagger documentation on local repository 3 | The full tutorial can be found [here](https://medium.com/the-andela-way/splitting-your-swagger-spec-into-multiple-files-in-a-node-project-2019575b0ced) 4 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "tutorial", 3 | "version": "1.0.0", 4 | "description": "", 5 | "main": "swagger.js", 6 | "directories": { 7 | "doc": "docs" 8 | }, 9 | "scripts": { 10 | "start": "node swagger.js", 11 | "test": "echo \"Error: no test specified\" && exit 1" 12 | }, 13 | "author": "", 14 | "license": "ISC", 15 | "dependencies": { 16 | "express": "^4.16.3", 17 | "swagger-jsdoc": "^6.2.1", 18 | "swagger-ui-express": "^4.5.0" 19 | } 20 | } 21 | -------------------------------------------------------------------------------- /swagger.js: -------------------------------------------------------------------------------- 1 | const express = require('express'); 2 | const swaggerUi = require('swagger-ui-express'); 3 | const swaggerSpec = require('./configuration/swagger') 4 | 5 | // Create global app objects 6 | const app = express(); 7 | 8 | // use swagger-Ui-express for your app documentation endpoint 9 | app.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec)); 10 | 11 | // Your Routes start here 12 | 13 | // Your Routes end here 14 | 15 | // finally, let's start our server... 16 | const server = app.listen(process.env.PORT || 3000, () => { 17 | // eslint-disable-next-line no-console 18 | console.log(`'Listening on port '${server.address().port}`); 19 | }); 20 | -------------------------------------------------------------------------------- /configuration/swagger.js: -------------------------------------------------------------------------------- 1 | const swaggerJSDoc = require('swagger-jsdoc'); 2 | 3 | const swaggerDefinition = { 4 | info: { 5 | title: 'REST API for my App', // Title of the documentation 6 | version: '1.0.0', // Version of the app 7 | description: 'This is the REST API for my product', // short description of the app 8 | }, 9 | host: 'localhost:3000', // the host or url of the app 10 | basePath: '/api', // the basepath of your endpoint 11 | }; 12 | 13 | // options for the swagger docs 14 | const options = { 15 | // import swaggerDefinitions 16 | swaggerDefinition, 17 | // path to the API docs 18 | apis: ['./docs/**/*.yaml'], 19 | }; 20 | // initialize swagger-jsdoc 21 | module.exports = swaggerJSDoc(options); -------------------------------------------------------------------------------- /docs/user.yaml: -------------------------------------------------------------------------------- 1 | paths: 2 | /users/: # path of the user from your endpoint 3 | post: # endpoint request type (post request) 4 | tags: # Tag property 5 | - User # Value of the tag 6 | summary: creates a new user 7 | produces: 8 | - application/json 9 | parameters: # request parameters 10 | - in: body # request body 11 | name: sign up # name of request, can be any name 12 | description: It enables a user to create an account 13 | required: false # can also be true depending on user preference 14 | schema: # Schema definition 15 | $ref: '#/definitions/signUp' 16 | responses: # server responses 17 | 201: 18 | description: An object with user details 19 | definitions: # Schema defination for request body 20 | signUp: 21 | type: object 22 | properties: 23 | user: 24 | type: object 25 | properties: 26 | username: 27 | type: string 28 | email: 29 | type: string 30 | password: 31 | type: string 32 | -------------------------------------------------------------------------------- /docs/pet.yaml: -------------------------------------------------------------------------------- 1 | paths: 2 | /pet/{id}: # path of the user from your endpoint 3 | put: # endpoint request type (put request) 4 | tags: 5 | - Pet 6 | summary: It updates a pet profile detail 7 | produces: 8 | - application/json 9 | parameters: # request parameters 10 | - name: id # name of parameter passed 11 | in: path # parameters in the path 12 | description: path parameter takes the pet id 13 | required: true 14 | type: string 15 | - in: body 16 | name: update pet 17 | description: It enables a user to update pet profile 18 | required: false 19 | schema: 20 | $ref: '#/definitions/updatePet' 21 | responses: 22 | 200: 23 | description: An object with a user updated user profile detail 24 | 401: 25 | description: Unauthorized users 26 | definitions: # Schema definition for the request body 27 | updatePet: 28 | type: object 29 | properties: 30 | pet: 31 | type: object 32 | properties: 33 | petname: 34 | type: string 35 | petFavorite: 36 | type: string 37 | image: 38 | type: string 39 | password: 40 | type: string --------------------------------------------------------------------------------