前端express 框架swagger 遇到了接口只能一种情况,是不是,swagger的接口要放入不同文件啊,比如不同 请求路径的api 接口如何写
是的,如果接口只有一种情况,可以将其定义在一个文件中。但是,如果有不同请求路径的接口,最好将它们分别定义在不同的文件中,以便于管理和维护。
在使用swagger时,可以按照以下步骤来定义不同请求路径的api接口:
-
创建一个swagger文档,可以使用yaml或json格式。
-
在文档中定义每个接口的请求路径,如:
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'
- 在文档中定义每个接口的请求方式和参数,如:
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'
- 定义每个接口的请求参数和响应参数的数据类型和格式,如:
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
- 在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 著作权归作者所有。请勿转载和采集!