Getting Started with Swagger-UI-Express

Swagger-UI-Express is a powerful tool that integrates the Swagger UI with your Express application. It allows you to serve auto-generated API documentation from your OpenAPI Specification, making it easier for developers to understand and interact with your API.

Installation

  npm install swagger-ui-express
  npm install swagger-jsdoc

Basic Setup

Below is an example setup for integrating Swagger-UI-Express in an Express.js application:

  const express = require('express');
  const swaggerUi = require('swagger-ui-express');
  const swaggerJsdoc = require('swagger-jsdoc');
  
  const app = express();

  const swaggerOptions = {
    definition: {
      openapi: '3.0.0',
      info: {
        title: 'My API',
        version: '1.0.0',
        description: 'This is a sample API documentation.'
      },
    },
    apis: ['./routes/*.js'], // Path to the API docs
  };

  const swaggerDocs = swaggerJsdoc(swaggerOptions);
  app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));

  app.listen(3000, () => console.log('Server running on http://localhost:3000'));

API Examples

Below are some sample API endpoints and their corresponding Swagger annotations:

GET /users

  /**
   * @swagger
   * /users:
   *   get:
   *     summary: Retrieve a list of users
   *     responses:
   *       200:
   *         description: A list of users
   *         content:
   *           application/json:
   *             schema:
   *               type: array
   *               items:
   *                 type: object
   */

  app.get('/users', (req, res) => {
    res.json([
      { id: 1, name: 'John Doe' },
      { id: 2, name: 'Jane Doe' }
    ]);
  });

POST /users

  /**
   * @swagger
   * /users:
   *   post:
   *     summary: Add a new user
   *     requestBody:
   *       required: true
   *       content:
   *         application/json:
   *           schema:
   *             type: object
   *             required:
   *               - name
   *             properties:
   *               name:
   *                 type: string
   *     responses:
   *       201:
   *         description: User created successfully
   */

  app.post('/users', (req, res) => {
    const newUser = req.body;
    newUser.id = Date.now();
    res.status(201).json(newUser);
  });

GET /users/:id

  /**
   * @swagger
   * /users/{id}:
   *   get:
   *     summary: Retrieve a single user by ID
   *     parameters:
   *       - in: path
   *         name: id
   *         required: true
   *         schema:
   *           type: integer
   *     responses:
   *       200:
   *         description: A user object
   */

  app.get('/users/:id', (req, res) => {
    const user = users.find(u => u.id === parseInt(req.params.id));
    if (user) {
      res.json(user);
    } else {
      res.status(404).send('User not found');
    }
  });

Using the above sample endpoint definitions, you can easily document and test APIs. Adding Swagger-UI-Express to your project will greatly enhance its usability and maintainability, especially in environments where APIs evolve rapidly.

Start utilizing Swagger-UI-Express today to create interactive and detailed documentation for your APIs, making it easier for developers to explore and understand your services.

Complete Example

  const express = require('express');
  const bodyParser = require('body-parser');
  const swaggerUi = require('swagger-ui-express');
  const swaggerJsdoc = require('swagger-jsdoc');

  const app = express();
  app.use(bodyParser.json());

  const swaggerOptions = {
    definition: {
      openapi: '3.0.0',
      info: {
        title: 'My API',
        version: '1.0.0',
        description: 'This is a sample API documentation.'
      },
    },
    apis: ['./app.js'],
  };

  const swaggerDocs = swaggerJsdoc(swaggerOptions);
  app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));

  let users = [
    { id: 1, name: 'John Doe' },
    { id: 2, name: 'Jane Doe' },
  ];

  app.get('/users', (req, res) => {
    res.json(users);
  });

  app.post('/users', (req, res) => {
    const newUser = req.body;
    newUser.id = Date.now();
    users.push(newUser);
    res.status(201).json(newUser);
  });

  app.get('/users/:id', (req, res) => {
    const user = users.find(u => u.id === parseInt(req.params.id));
    if (user) {
      res.json(user);
    } else {
      res.status(404).send('User not found');
    }
  });

  app.listen(3000, () => console.log('Server running on http://localhost:3000'));

Consider integrating this powerful tool in your Express applications to streamline API development and maximize efficiency.

Hash: e4f6e0d28d3af195365898700a83b18695cf2b70442eeadf94e1a45653526c71