###### tags: `swagger`
# Swagger-ui setup

Swagger-ui is a web interface for the Swagger API documentation. It is a static web page that can be served from any web server.

## Installation

1. Add `swagger.json` at the same level as `app.js` and `package.json`:

swagger.json example:

   {
     "openapi": "3.0.0",
     "info": {
       "title": "User API",
       "description": "Simple RESTful API in Node.js with TypeScript",
       "version": "0.0.1"
     },
     "servers": [
       {
         "url": "http://localhost:3000/api",
         "description": "Local server"
       }
     ]
   }

2. Install fellowing packages:

   npm install --save-dev swagger-ui-express swagger-jsdoc

3. In `app.js` add the following code:

   const swaggerUi = require('swagger-ui-express');
   const swaggerDocument = require('./swagger.json');

   app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

### Css customization

Adjust the `app.js` file to include the following code:

// swagger-ui docs
var options = {
  customCss:
    ".swagger-ui .topbar { background-color: #fab2ea} .topbar-wrapper img {content:url('../assets/logo.gif'); width:auto; height:30px;}",
  customSiteTitle: 'API Docs',
  customfavIcon: '/assets/favicon.ico',
};
app.use(
  '/api-docs',
  swaggerUi.serve,
  swaggerUi.setup(swaggerDocument, options)
);

# Auto generate swagger.json

[swagger-autogen](https://israynotarray.com/nodejs/20201229/1974873838/) is a tool that can automatically generate swagger.json from JSDoc comments in your code.

1. Install fellowing packages:

   npm install --save swagger-autogen swagger-ui-express

2. Create a file called `swagger.js` in the root of your project and add the following code:

   const swaggerAutogen = require('swagger-autogen')();

   const outputFile = './swagger.json';
   const endpointsFiles = ['./app.js'];

   swaggerAutogen(outputFile, endpointsFiles);

3. Modify `package.json` to add the following script:

   "scripts": {
     "swagger-autogen": "node swagger.js"
   }

4. Run the following command to generate `swagger.json`:

   npm run swagger-autogen

# What's in url？ parameter, query
- wedgets = parameter
- colour = query
- blue = query value