# simple and best way to document a rest api created in nodejs
The best and simplest way to document a Node.js REST API is to use the [Swagger/OpenAPI specification](https://www.google.com/search?client=ubuntu-sn&channel=fs&q=Swagger%2FOpenAPI+specification&mstk=AUtExfBkf1TCFmy-XeGI2Qu0qyDR6M50mbfInI36mzivEgxjR3VmrNuA55DGEXPNMBI_M2U9S98k5MjemEu3bMDIz7wPpb0_Wv6lplFDYLHao-llLwGdsqZ1KwIPVrCBDyjuMwdpJKyofSWYYThawL262u-zbLZ8_F9NB3euNAPYgzlm7SY&csui=3&ved=2ahUKEwiS-9K434qRAxVyR2wGHaLMGWAQgK4QegQIARAE) with tools like [swagger-jsdoc](https://www.google.com/search?client=ubuntu-sn&channel=fs&q=swagger-jsdoc&mstk=AUtExfBkf1TCFmy-XeGI2Qu0qyDR6M50mbfInI36mzivEgxjR3VmrNuA55DGEXPNMBI_M2U9S98k5MjemEu3bMDIz7wPpb0_Wv6lplFDYLHao-llLwGdsqZ1KwIPVrCBDyjuMwdpJKyofSWYYThawL262u-zbLZ8_F9NB3euNAPYgzlm7SY&csui=3&ved=2ahUKEwiS-9K434qRAxVyR2wGHaLMGWAQgK4QegQIARAF) and [swagger-ui-express](https://www.google.com/search?client=ubuntu-sn&channel=fs&q=swagger-ui-express&mstk=AUtExfBkf1TCFmy-XeGI2Qu0qyDR6M50mbfInI36mzivEgxjR3VmrNuA55DGEXPNMBI_M2U9S98k5MjemEu3bMDIz7wPpb0_Wv6lplFDYLHao-llLwGdsqZ1KwIPVrCBDyjuMwdpJKyofSWYYThawL262u-zbLZ8_F9NB3euNAPYgzlm7SY&csui=3&ved=2ahUKEwiS-9K434qRAxVyR2wGHaLMGWAQgK4QegQIARAG). This approach involves writing documentation in a standard format (like a JavaScript/JSDoc comment block) that the `swagger-jsdoc` package parses into an OpenAPI specification. The `swagger-ui-express` package then serves this specification to generate an interactive and user-friendly documentation UI.
1. Set up your project
- **Initialize your project:**
- ```
mkdir my-api
cd my-api
npm init -y
```
- **Install necessary packages:**
- ```
npm install express swagger-ui-express swagger-jsdoc
```
- **Create a basic Express server** (`app.js`):
```
const express = require('express');
const app = express();
const port = 3000;
app.get('/', (req, res) => {
res.send('Hello World!');
});
app.listen(port, () => {
console.log(`Server listening at http://localhost:${port}`);
});
```
2. Define the API documentation
- **Create a file for your documentation specification** (e.g., `swaggerDocs.js`):
- ```
const swaggerJsdoc = require('swagger-jsdoc');
const options = {
definition: {
openapi: '3.0.0',
info: {
title: 'My Node.js API',
version: '1.0.0',
description: 'A sample REST API for testing documentation',
},
servers: [
{
url: 'http://localhost:3000',
description: 'Development server',
},
],
},
apis: ['./routes/*.js'], // Path to the API routes files
};
const swaggerSpec = swaggerJsdoc(options);
module.exports = swaggerSpec;
```
- **Add JSDoc comments to your route files** (e.g., `routes/userRoutes.js`) to define the endpoints:
```
// routes/userRoutes.js
/**
* @openapi
* /users:
* get:
* summary: Get all users
* tags:
* - Users
* responses:
* '200':
* description: A list of users
* content:
* application/json:
* schema:
* type: array
* items:
* $ref: '#/components/schemas/User'
*/
// ... your router code
```
3. Integrate with your Express app
- **Require the Swagger UI Express and your Swagger specification** in your `app.js` file:
```
const express = require('express');
const app = express();
const port = 3000;
const swaggerUi = require('swagger-ui-express');
const swaggerSpec = require('./swaggerDocs.js'); // Path to your swaggerDocs.js
// ... (your existing code)
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
// ... (rest of your app.js)
```
4. Run the server
- **Start your server:**
- ```
node app.js
```
- **Access the interactive documentation** by navigating to `http://localhost:3000/api-docs` in your browser