Incorporer Swagger avec JSDoc dans un projet TypeScript.

Installer les dépendances:

npm install swagger-jsdoc swagger-ui-express -S
npm install @types/swagger-ui-express @types/swagger-jsdoc -D

Exemple de fichier SwaggerSpec.ts:

import * as swaggerJsdoc from 'swagger-jsdoc';
 
const swaggerDefinition = {
  info: {
    title: 'Portfolio API',
    version: '0.1.0',
    description: 'This is the REST API for Portfolio Client',
  },
  basePath: '/api/v1',
};
 
const options = {
  swaggerDefinition,
  explorer: true,
  apis: ['**/*.ts'],
};
 
export const swaggerSpec = swaggerJsdoc(options);

Là ou app d'Express est disponible, ou bien là où les middlewares sont injectés:

import * as swaggerUi from 'swagger-ui-express';
import { swaggerSpec } from './SwaggerSpec';
 
// ...
 
 
if (process.env.NODE_ENV !== 'production') {
  app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
}

  /**
   * @swagger
   * /application/status:
   *   get:
   *     description: Application's status
   *     tags: [Application]
   *     produces:
   *       - application/json
   *     responses:
   *       200:
   *         description: Application status
   */

Documentation officielle - Describing Parameters

Header:

   *     parameters:
   *     - in: header
   *       name: x-auth-token
   *       description: Auth Token
   *       schema:
   *         type: string
   *       required: true

Body:

   *     parameters:
   *     - in: body
   *       name: Portfolio information
   *       description: Provide needed Portfolio Information to create it
   *       required: true
   *       schema:
   *         type: object
   *         properties:
   *           name:
   *             type: string
   *             required: true
   *           description:
   *             type: string
   *             required: false

Path:

   * /portfolios/:portfolioId:
   * 
   * ...
   * 
   *     - in: path
   *       name: portfolio id
   *       type: string
   *       required: true
   *       description: Portfolio Id

/**
 * @swagger
 * tags:
 *   name: Users
 *   description: User management
 */