在 js 代码中使用注释来书写,十分不方便:

  • 造成代码混乱
  • 缩进困难
  • 复制官方文档配置困难

所以,我认为更好的方案是直接使用YAML文件来配置。

  • 在根目录新建docs/frontdocs/admin目录,分别用来存放前台和后台的接口文档。
  • 新建docs/admin/articles.yaml文件
openapi: 3.0.0
info:
  title: Sample API
  description: 长乐未央教学使用
  version: 0.0.1

servers:
  - url: http://localhost:3000
    description: 开发环境
  - url: https://clwy.cn
    description: 生产环境

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: token
  schemas:
    Articles:
      type: object
      properties:
        articles:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
                example: 1
              title:
                type: string
                example: 明天可能下雨
              content:
                type: string
                example: 哈哈哈哈
    Article:
      type: object
      properties:
        id:
          type: integer
          example: 1
        title:
          type: string
          example: 明天可能下雨
        content:
          type: string
          example: 哈哈哈哈
      required:
        - title
        - content
paths:
  /admin/articles:
    get:
      summary: 查询文章列表
      description: 可以传递分页和模糊查询参数
      security:
        - ApiKeyAuth: [ ]
      tags:
        - 文章
      parameters:
        - name: title
          in: query
          required: false
          description: 模糊查询参数。
          schema:
            type: string
        - name: currentPage
          in: query
          required: false
          description: 当前是第几页。
          schema:
            type: integer
            default: 1
      responses:
        '200': # 状态码
          description: 文章列表的json格式数据
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Articles'
        '404':
          description: 页面未找到
    post:
      summary: 新增文章
      security:
        - ApiKeyAuth: [ ]
      tags:
        - 文章
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Article'
          application/json:
            schema:
              $ref: '#/components/schemas/Article'
      responses:
        '200':
          description: 新增文章成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Article'
  /admin/articles/{articleId}:
    get:
      summary: 查询单条文章
      security:
        - ApiKeyAuth: [ ]
      tags:
        - 文章
      parameters:
        - name: articleId
          in: path
          required: true
          description: 文章的id
          example: 1
          schema:
            type: integer
            minimum: 1
      responses:
        '200':
          description: 返回的当前文章
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Article'
        '404':
          description: 页面未找到
    put:
      summary: 修改文章
      security:
        - ApiKeyAuth: [ ]
      tags:
        - 文章
      parameters:
        - name: articleId
          in: path
          required: true
          description: 文章的id
          example: 1
          schema:
            type: integer
            minimum: 1
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Article'
          application/json:
            schema:
              $ref: '#/components/schemas/Article'
      responses:
        '200':
          description: 返回的当前修改文章
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Article'
        '404':
          description: 页面未找到
    delete:
      summary: 删除文章
      security:
        - ApiKeyAuth: [ ]
      tags:
        - 文章
      parameters:
        - name: articleId
          in: path
          required: true
          description: 文章的id
          example: 1
          schema:
            type: integer
            minimum: 1
      responses:
        '200':
          description: 删除成功
        '404':
          description: 页面未找到

修改 app.js

const swaggerJSDocOptions = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: '长乐未央',
      version: '1.0.0',
    },
  },
  apis: ['./docs/front/*.yaml', './docs/admin/*.yaml'],    // <-----------
};

已添加到喜欢了