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-api-key
   *       description: API Key
   *       required: true
   *       schema:
   *         type: string

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

Response comme objet:

   *     responses:
   *       200:
   *         description: Authentication information
   *         schema:
   *           type: object
   *           properties:
   *             token:
   *               type: string
   *             accountIds:
   *               type: array
   *               items:
   *                 type: string

   *     responses:
   *       200:
   *         description: Application status
   *         schema:
   *           $ref: '#/definitions/ApplicationStatusResponse'
   * definitions:
   *   ApplicationStatusResponse:
   *     properties:
   *       name:
   *         type: string
   *       version:
   *         type: string
   *       env:
   *         type: string
   *       uptime:
   *         type: integer

Réponse qui est une liste

   *     responses:
   *       200:
   *         description: Portfolio Information
   *         schema:
   *           type: 'array'
   *           items:
   *             $ref: '#/definitions/SerializedModel'

/**
 * @swagger
 *  components:
 *    schemas:
 *      User:
 *        type: object
 *        required:
 *          - name
 *          - email
 *        properties:
 *          name:
 *            type: string
 *          email:
 *            type: string
 *            format: email
 *            description: Email for the user, needs to be unique.
 *        example:
 *           name: Alexander
 *           email: fake@email.com
 */

Schema Reference:

 *         schema:
 *           $ref: '#/definitions/CustomModel'

Schema avec enum:

          schema:
            type: string
            enum: [asc, desc]

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

/**
 * @swagger
 *
 *  tags:
 *    - name: pets
 *      description: Everything about your Pets
 *      externalDocs:
 *        url: http://docs.my-api.com/pet-operations.htm
 *    - name: store
 *      description: Access to Petstore orders
 *      externalDocs:
 *        url: http://docs.my-api.com/store-orders.htm
 */

Utilisation:

/**
 * @swagger
 *  paths:
 *    /pet/findByStatus:
 *      get:
 *        summary: Finds pets by Status
 *        tags:
 *          - pets
 *        ...
 *    /pet:
 *      post:
 *        summary: Adds a new pet to the store
 *        tags:
 *          - pets
 *        ...
 *    /store/inventory:
 *      get:
 *        summary: Returns pet inventories
 *        tags:
 *          - store
 *        ...
 */

• Swagger: Time to document that Express API you built!

Option avec JSON Spec:

• Your NodeJS TypeScript API is Nothing Without Swagger-UI

Option avec YAML Spec:

• The Easiest Way To Start Using Swagger in Node.js

Generateurs:

• tsoa