├── .gitignore ├── README.md ├── app.js ├── assets └── autogen-node-swagger-docs.png └── package.json /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Simple NodeJS API Server 2 | 3 | In this example application, we use Swagger JSDoc and Swagger UI Express to automatically generate OpenAPI documentation. We create a simple NodeJS API server to demonstrate the power of autogenerated documentation. 4 | 5 | ## Tutorial Available 6 | 7 | [YouTube: Autogenerating Swagger Documentation with Node & Express](https://www.youtube.com/watch?v=apouPYPh_as) 8 | 9 | [![Autogenerating Swagger Documentation with Node & Express](assets/autogen-node-swagger-docs.png)](https://www.youtube.com/watch?v=apouPYPh_as "Autogenerating Swagger Documentation with Node & Express") 10 | 11 | ## Running the Server 12 | 13 | With [NodeJS](https://nodejs.org/en/) installed, you can started the server by running, 14 | 15 | ```sh 16 | node app.js 17 | ``` 18 | 19 | _**OR**_ 20 | 21 | ```sh 22 | npm run start 23 | ``` 24 | 25 | ## Accessing the Docs 26 | 27 | With your local server running, the generated docs are available here: [http://localhost:5000/api-docs](http://localhost:5000/api-docs) 28 | 29 | ## Development 30 | 31 | This simple server can be easily extended. After cloning this [repository](https://github.com/brian-childress/node-autogenerate-swagger-documentation) you can start developing locally. 32 | 33 | ### Locally (without Docker) 34 | 35 | 1) Install [Nodemon](https://www.npmjs.com/package/nodemon), Nodemon will watch for file changes and restart the NodeJS process. This allows for faster development and testing. 36 | 37 | ```sh 38 | npm install -g nodemon 39 | ``` 40 | 41 | 2) With Nodemon installed, start the server using Nodemon 42 | 43 | ```sh 44 | nodemon app.js 45 | ``` 46 | 47 | _**OR**_ 48 | 49 | ```sh 50 | npm run start:dev 51 | ``` 52 | 53 | ### Using Docker 54 | 55 | I prefer to use Docker for local development wherever possible. This allows me to have a consistent development environment. 56 | 57 | #### Start Docker Container 58 | 59 | With Docker installed, we can start a container using the latest NodeJS Docker image. 60 | 61 | ```sh 62 | docker run -it --rm -p 5000:5000 -v $(pwd):/api -w="/api" node bash 63 | ``` 64 | 65 | Start the application in development mode using Nodemon inside your Docker Container 66 | 67 | ```sh 68 | npm run start:dev 69 | ``` 70 | 71 | To stop your running NodeJS API server 72 | 73 | ```sh 74 | ctrl + c 75 | ``` 76 | 77 | To quit your Docker Container development environment, in your terminal: 78 | 79 | ```sh 80 | exit 81 | ``` 82 | 83 | This will cleanup any running containers, (note: the Docker image will still exist on your machine) -------------------------------------------------------------------------------- /app.js: -------------------------------------------------------------------------------- 1 | const express = require("express"); 2 | const app = express(); 3 | const swaggerJsDoc = require("swagger-jsdoc"); 4 | const swaggerUi = require("swagger-ui-express"); 5 | 6 | const port = process.env.PORT || 5000; 7 | 8 | // Extended: https://swagger.io/specification/#infoObject 9 | const swaggerOptions = { 10 | swaggerDefinition: { 11 | info: { 12 | version: "1.0.0", 13 | title: "Customer API", 14 | description: "Customer API Information", 15 | contact: { 16 | name: "Amazing Developer" 17 | }, 18 | servers: ["http://localhost:5000"] 19 | } 20 | }, 21 | // ['.routes/*.js'] 22 | apis: ["app.js"] 23 | }; 24 | 25 | const swaggerDocs = swaggerJsDoc(swaggerOptions); 26 | app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(swaggerDocs)); 27 | 28 | // Routes 29 | /** 30 | * @swagger 31 | * /customers: 32 | * get: 33 | * description: Use to request all customers 34 | * responses: 35 | * '200': 36 | * description: A successful response 37 | */ 38 | app.get("/customers", (req, res) => { 39 | res.status(200).send("Customer results"); 40 | }); 41 | 42 | /** 43 | * @swagger 44 | * /customers: 45 | * put: 46 | * description: Use to return all customers 47 | * parameters: 48 | * - name: customer 49 | * in: query 50 | * description: Name of our customer 51 | * required: false 52 | * schema: 53 | * type: string 54 | * format: string 55 | * responses: 56 | * '201': 57 | * description: Successfully created user 58 | */ 59 | app.put("/customer", (req, res) => { 60 | res.status(200).send("Successfully updated customer"); 61 | }); 62 | 63 | app.listen(port, () => { 64 | console.log(`Server listening on port ${port}`); 65 | }); 66 | -------------------------------------------------------------------------------- /assets/autogen-node-swagger-docs.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/brian-childress/node-autogenerate-swagger-documentation/6d93596edeee652409c76fd8ff0537bd3b76fad4/assets/autogen-node-swagger-docs.png -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "api", 3 | "version": "1.0.0", 4 | "description": "", 5 | "main": "index.js", 6 | "scripts": { 7 | "test": "echo \"Error: no test specified\" && exit 1" 8 | }, 9 | "keywords": [], 10 | "author": "", 11 | "license": "ISC", 12 | "dependencies": { 13 | "express": "^4.17.1", 14 | "swagger-jsdoc": "^3.4.0", 15 | "swagger-ui-express": "^4.0.7" 16 | } 17 | } 18 | --------------------------------------------------------------------------------