是的,如果接口只有一种情况,可以将其定义在一个文件中。但是,如果有不同请求路径的接口,最好将它们分别定义在不同的文件中,以便于管理和维护。

在使用swagger时,可以按照以下步骤来定义不同请求路径的api接口:

  1. 创建一个swagger文档,可以使用yaml或json格式。

  2. 在文档中定义每个接口的请求路径,如:

paths:
  /users:
    get:
      summary: 获取用户列表
      parameters:
        - name: limit
          in: query
          description: 每页显示的记录数
          type: integer
          default: 20
        - name: page
          in: query
          description: 当前页数
          type: integer
          default: 1
      responses:
        '200':
          description: 成功
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
  1. 在文档中定义每个接口的请求方式和参数,如:
paths:
  /users:
    get:
      summary: 获取用户列表
      parameters:
        - name: limit
          in: query
          description: 每页显示的记录数
          type: integer
          default: 20
        - name: page
          in: query
          description: 当前页数
          type: integer
          default: 1
      responses:
        '200':
          description: 成功
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
    post:
      summary: 创建用户
      parameters:
        - name: user
          in: body
          description: 用户信息
          schema:
            $ref: '#/definitions/User'
      responses:
        '200':
          description: 成功
          schema:
            $ref: '#/definitions/User'
  1. 定义每个接口的请求参数和响应参数的数据类型和格式,如:
definitions:
  User:
    type: object
    properties:
      id:
        type: integer
        format: int64
      username:
        type: string
      email:
        type: string
        format: email
      phone:
        type: string
        format: phone
      createdAt:
        type: string
        format: date-time
      updatedAt:
        type: string
        format: date-time
  1. 在express应用中使用swagger-ui-express和swagger-jsdoc中间件,将swagger文档展示在浏览器中,如:
const swaggerUi = require('swagger-ui-express');
const swaggerJSDoc = require('swagger-jsdoc');

const options = {
    swaggerDefinition: {
        info: {
            title: 'API文档',
            version: '1.0.0',
            description: 'API接口文档',
        },
        basePath: '/api/v1',
    },
    apis: ['routes/*.js'],
};

const swaggerSpec = swaggerJSDoc(options);

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

其中,apis参数指定了包含所有路由文件的目录,每个路由文件中都可以定义对应的swagger接口。


原文地址: https://www.cveoy.top/t/topic/sy7 著作权归作者所有。请勿转载和采集!

免费AI点我,无需注册和登录