Swagger setting

Installation

• swagger-jsdoc
  • This library reads your JSDoc-annotated source code and generates an OpenAPI (Swagger) specification
• swagger-ui-express
  • This module allows you to serve auto-generated swagger-ui generated API docs from express

npm i swagger-jsdoc swagger-ui-express

npm i -D @types/swagger-jsdoc @types/swagger-ui-express

Settings

• entry file index.js

import swaggerUi from 'swagger-ui-express';
import { swaggerSpec } from './config/swagger';
import { logger, morganMiddleware } from './config/winston';

app.use(morganMiddleware);

app.use('/swagger', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

• config file swagger.ts

import swaggerJSDoc from 'swagger-jsdoc';
import packageJson from '../../package.json';

const options = {
  swaggerDefinition: {
    info: {
      title: packageJson.name,
      version: packageJson.version,
      description: packageJson.description || packageJson.name
    },
    basePath: '/api/'
  },
  apis: ['./src/routes/v1/index.ts']
};

export const swaggerSpec = swaggerJSDoc(options);

• ./src/routes/v1/index.ts
  • As we have configured settings in that swagger.ts above, so 'swagger-jsdoc' library will take the contents of @openapi (or @swagger) with the above configuration, now we will have to tell the library details of every api

import { Router } from 'express';
import checkIp from './checkIp';
import contact from './contact';
import focus from './focus';
import news from './news';
import notice from './notice';
import quotation from './quotation';
import response from './response';

const router = Router();

/**
 * @swagger
 * /checkIp:
 *   get:
 *     summary: 偵測 IP 來源地區
 *     responses:
 *       200:
 *         description: OK
 *       400:
 *         description: Client error
 *       500:
 *         description: Server error
 */
router.use('/checkIp', checkIp);

/**
 * @swagger
 * /contact:
 *   post:
 *     summary: 聯繫我們
 *     parameters:
 *     - name: body
 *       in: body
 *       type: object
 *       properties:
 *         name:
 *           type: string
 *         surname:
 *           type: string
 *         mobile:
 *           type: string
 *         email:
 *           type: string
 *         area:
 *           type: string
 *         type:
 *           type: string
 *         iScustomer:
 *           type: string
 *         login:
 *           type: string
 *         content:
 *           type: string
 *       required:
 *           - name
 *           - surname
 *           - mobile
 *           - email
 *           - area
 *           - type
 *     responses:
 *       200:
 *         description: OK
 *       400:
 *         description: Client error
 *       500:
 *         description: Server error
 */

router.use('/contact', contact);

/**
 * @swagger
 * /focus:
 *   get:
 *     summary: 財經新聞
 *     parameters:
 *     - name: lang
 *       in: query
 *       required: true
 *       type: string
 *     responses:
 *       200:
 *         description: OK
 *       400:
 *         description: Client error
 *       500:
 *         description: Server error
 */
router.use('/focus', focus);

/**
 * @swagger
 * /news:
 *   get:
 *     summary: 取得即時新聞
 *     responses:
 *       200:
 *         description: OK
 *       400:
 *         description: Client error
 *       500:
 *         description: Server error
 */
router.use('/news', news);

/**
 * @swagger
 * /notice:
 *   get:
 *     summary: 平台公告
 *     parameters:
 *     - name: lang
 *       in: query
 *       required: true
 *       type: string
 *     responses:
 *       200:
 *         description: OK
 *       400:
 *         description: Client error
 *       500:
 *         description: Server error
 */
router.use('/notice', notice);

/**
 * @swagger
 * /quotation:
 *   get:
 *     summary: 市場分析
 *     parameters:
 *     - name: lang
 *       in: query
 *       required: true
 *       type: string
 *     responses:
 *       200:
 *         description: OK
 *       400:
 *         description: Client error
 *       500:
 *         description: Server error
 */
router.use('/quotation', quotation);

/**
 * @swagger
 * /response:
 *   get:
 *     summary: 企業責任
 *     parameters:
 *     - name: lang
 *       in: query
 *       required: true
 *       type: string
 *     responses:
 *       200:
 *         description: OK
 *       400:
 *         description: Client error
 *       500:
 *         description: Server error
 */
router.use('/response', response);

export default router;