使用 components 复用定义Schema(数据模型)复用components 允许您定义可在整个 API 文档中重复使用的元素减少重复并确保一致性:实例components:schemas:User:type: objectproperties:id:type: integerformat: int64username:type: stringemail:type: string引用方式实例paths:/users/{id}:get:responses:200:description: 用户信息content:application/json:schema:$ref: #/components/schemas/UserParameters(公共参数)复用定义常用参数实例components:parameters:PageParam:name: pagein: queryschema:type: integerdefault: 1description: 页码LimitParam:name: limitin: queryschema:type: integerdefault: 10description: 每页记录数引用方式实例paths:/products:get:parameters:- $ref: #/components/parameters/PageParam- $ref: #/components/parameters/LimitParamResponses(通用响应)复用定义标准响应实例components:responses:NotFound:description: 资源未找到content:application/json:schema:type: objectproperties:code:type: integerexample: 404message:type: stringexample: 资源不存在BadRequest:description: 请求参数错误content:application/json:schema:type: objectproperties:code:type: integerexample: 400message:type: string引用方式实例paths:/users/{id}:get:responses:200:description: 成功content:application/json:schema:$ref: #/components/schemas/User404:$ref: #/components/responses/NotFound400:$ref: #/components/responses/BadRequestAPI 版本控制通过 servers 区分版本实例servers:- url: https://api.example.com/v1description: API v1- url: https://api.example.com/v2description: API v2通过路径区分版本实例paths:/v1/users:get:# v1 用户接口.../v2/users:get:# v2 用户接口...通过请求头区分版本实例paths:/users:get:parameters:- name: api-versionin: headerrequired: trueschema:type: stringenum: [1.0, 2.0]Mock 数据模拟使用 examples 定义示例数据在响应中定义示例实例paths:/users:get:responses:200:description: 用户列表content:application/json:schema:type: arrayitems:$ref: #/components/schemas/Userexamples:userList:summary: 样例用户列表value:- id: 1username: user1email: user1example.com- id: 2username: user2email: user2example.com使用 Swagger UI Mock 功能Swagger UI 集成了模拟服务器可以基于您的 OpenAPI 定义生成模拟响应。配置 mockServer 到 Swagger UI实例SwaggerUI({url: https://petstore.swagger.io/v2/swagger.json,dom_id: #swagger-ui,presets: [SwaggerUI.presets.apis,SwaggerUIStandalonePreset],plugins: [SwaggerUI.plugins.MockPlugin],mockImplementations: {/users: {get: () ({status: 200,body: [{ id: 1, name: Test User 1 },{ id: 2, name: Test User 2 }]})}}})使用第三方 Mock 服务Prism: OpenAPI 模拟服务器Mockoon: 可与 Swagger 集成的模拟 API 工具Postman: 提供 mock 服务器功能高级安全配置定义多种认证方法实例components:securitySchemes:bearerAuth:type: httpscheme: bearerbearerFormat: JWTapiKeyAuth:type: apiKeyin: headername: X-API-KEYOAuth2:type: oauth2flows:implicit:authorizationUrl: https://example.com/oauth/authorizescopes:read: 读取权限write: 写入权限应用安全定义实例security:- bearerAuth: []- apiKeyAuth: []paths:/users:get:security:- OAuth2: [read]文档分离与组织使用 $ref 引用外部文件实例paths:/users:$ref: ./paths/users.yaml/products:$ref: ./paths/products.yamlcomponents:schemas:User:$ref: ./schemas/user.yaml标签与分组使用标签组织 API 端点实例tags:- name: usersdescription: 用户管理- name: productsdescription: 产品管理paths:/users:get:tags:- users/products:get:tags:- products扩展字段通过 x- 前缀添加自定义属性实例lpaths:/users:get:x-controller: UserControllerx-rate-limit: 100x-deprecated: false这些高级功能可以帮助您创建更加结构化、可维护和专业的 API 文档。