API documentation using swagger
Tags: api, documentation, javascript, webdev
Published: 2024-03-15 13:36:40

In this article, I will look at how to carry out API documentation. A pre-requisite for this tutorial is fore-hand knowledge of `YAML`.

When you create an API and you need to explain the API, you can make use of documentation provided by **Postman** or **Swagger**

**Swagger**: This is a tool to generate interactive API documentation.

**swagger-jsdoc**: To write the specifications.

**swagger-ui-express**: To serve the swagger UI in our application.


### Installation

```
mkdir server
cd server
npm run init -y
npm i swagger-jsdoc swagger-ui-express
```

**Swagger Options**

You need to create options/specifications for swagger ui

- Give OpenAPI version
- Give the URL of the server
- Define the file location of the API route (./route/products)

```javascript

// doc/swagger.js

import swaggerjsdoc from "swagger-jsdoc"

const options = {
    definition: {
        openapi: "3.0.0",
        info: {
            title: "Products API",
            version: "1.0.0",
            description: 'API Documentation for products API',
            contact: {
                name: 'Chima Ifeanyi',
                email: 'chimaifeanyi29@gmail.com'
            },
        },
        servers: [
            {
                url: "http://localhost:3500/",
            },
        ],
    },
    apis: ["./routes/*.js"],
};

export const swaggerSpecs = swaggerjsdoc(options);

```




### Creating Routes

Your documentation will be written in the file that contains the routes of your API

**Schema**: You need to create a schema to represent how your data will look like. The schema will be for reusability.

**Tags**: It is a good idea to group your requests into tags.

**Summary**: It gives a brief description of the API endpoint.

**Parameters**: This is to tell swagger that our API request has a parameter in the URL.


```javascript

// ./routes/routes.js

import express from "express";
export const router = express.Router();

import {productsController} from "../controllers/product.js";


/**
 * @swagger
 * components:
 *  schemas:
 *    Product:
 *     type: object
 *     required: 
 *      - name
 *      - price
 *      - category     
 *     properties:
 *      name:
 *        type: string
 *        description: The product name
 *      price:
 *         type: number
 *         description: The product price
 *      category:
 *          type: string
 *          description: The category
 *     example: 
 *        name: mango
 *        price: 400
 *        category: fruits
 */






/**
 * @swagger
 * tags:
 *  name: Products
 *  description: A products management API
 * 
 */






/**
 * @swagger
 * /home:
 *  get:
 *    summary: returns all the products
 *    tags: [Products]
 *    responses: 
 *      200:
 *        description: A list of all products
 *        content: 
 *          application/json:
 *             schema:
*                 type: array
*                 $ref: "#/components/schemas/Product"
 * 
 * 
 * 
 */

router.get("/", productsController.getProducts);


/**
 * @swagger
 * /home/{name}:
 *  get:
 *      summary: Get product by name
 *      tags: [Products]
 *      parameters:
 *        - in: path
 *          name: name
 *          schema:
 *              type: string
 *          required: true
 *          description: The product name
 *      responses:
 *          200:
 *              description: The product description by name
 *              contents:
 *                  application/json:
 *                      schema:
 *                          $ref: "#/components/schemas/Product"
 *          404:
 *              description: The product was not found
 */

router.get("/:name", productsController.getProductByName);




```







![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/uttd49qe68vlyh70im1e.gif)


It all comes together in our index.js


```javascript

// src/index.js

import express from "express";
import mongoose from "mongoose";
import cors from "cors";
import bodyParser from "body-parser";

import {corsOptions} from "./config/corsOptions.js";
import {connectDB} from "./config/dbConn.js";
import {swaggerSpecs} from "./docs/swagger.js"; // swagger specs
import swaggerui from "swagger-ui-express"; // swagger ui
import swaggerjsdoc from "swagger-jsdoc";


import {router} from "./routes/route.js"


const app = express();

app.use(express.json())


// Connect to MongoDB
connectDB(); 


// middleware to handle url encoded data
app.use(express.urlencoded({ extended: false }));


// built-in middleware for json
app.use(bodyParser.json());


// configuration for cors
app.use(cors(corsOptions));


app.use("/home", router)


// the route for api documentation.
app.use("/api-docs", swaggerui.serve, swaggerui.setup(swaggerSpecs))

app.use('*', (req, res)=>{
    res.status(404).json({ message: 'Endpoint does not exist'})
})


export default app

```


<a href="https://www.buymeacoffee.com/ifeanyichima" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy Me A Coffee" height="41" width="174"></a>

**Thank you, Please follow me**

[![HTML](https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white)](https://linkedin.com/in/ifeanyi-thankgod-chima)&nbsp;[![GitHub](https://img.shields.io/badge/GitHub-100000?style=for-the-badge&logo=github&logoColor=white)](https://github.com/masterifeanyi)