以下是一个完整的 Swagger 文档示例是一个用户管理系统 API 的详细规范。这个文档描述了一个用户管理系统的API包含了用户的基本信息、认证服务、数据模型等。该 API 遵循 RESTful 风格使用 JSON 格式进行数据交换。我们可以使用 Swagger Editor 在线测试你的文档在线地址SwaggerEditor。只需将你的 YAML 或 JSON 复制粘贴到编辑器中右侧面板将显示可视化的 API 文档。实例openapi: 3.0.0info:title: 我的第一个APIdescription: |这是一个简单的API示例文档展示了用户管理系统的基本功能。包括用户的查询、创建、更新和删除操作。version: 1.0.0contact:name: API 支持团队email: supportexample.comurl: https://www.example.com/supportlicense:name: Apache 2.0url: https://www.apache.org/licenses/LICENSE-2.0.htmlservers:- url: https://api.example.com/v1description: 生产环境- url: https://staging-api.example.com/v1description: 预发布环境- url: https://dev-api.example.com/v1description: 开发环境tags:- name: 用户description: 用户管理相关操作- name: 认证description: 认证相关操作paths:/users:get:tags:- 用户summary: 获取所有用户列表description: 返回系统中的所有用户信息支持分页和筛选operationId: getUsersparameters:- name: limitin: querydescription: 返回结果的最大数量required: falseschema:type: integerformat: int32minimum: 1maximum: 100default: 20- name: offsetin: querydescription: 分页偏移量required: falseschema:type: integerformat: int32minimum: 0default: 0- name: statusin: querydescription: 按用户状态筛选required: falseschema:type: stringenum: [active, inactive, banned]responses:200:description: 成功获取用户列表content:application/json:schema:type: objectproperties:total:type: integerdescription: 总用户数users:type: arrayitems:$ref: #/components/schemas/Userexample:total: 2users:- id: 1username: john_doeemail: johnexample.comstatus: activecreatedAt: 2023-05-01T12:00:00Z- id: 2username: jane_smithemail: janeexample.comstatus: activecreatedAt: 2023-05-02T14:30:00Z400:description: 无效请求content:application/json:schema:$ref: #/components/schemas/Error401:$ref: #/components/responses/UnauthorizedErrorsecurity:- bearerAuth: []post:tags:- 用户summary: 创建新用户description: 在系统中创建一个新用户operationId: createUserrequestBody:description: 用户信息required: truecontent:application/json:schema:$ref: #/components/schemas/NewUserexample:username: new_useremail: new_userexample.compassword: securePassword123responses:201:description: 用户创建成功content:application/json:schema:$ref: #/components/schemas/Userexample:id: 3username: new_useremail: new_userexample.comstatus: activecreatedAt: 2023-05-10T09:15:00Z400:description: 无效请求content:application/json:schema:$ref: #/components/schemas/Errorexample:code: 400message: 邮箱格式不正确409:description: 资源冲突content:application/json:schema:$ref: #/components/schemas/Errorexample:code: 409message: 用户名已存在401:$ref: #/components/responses/UnauthorizedErrorsecurity:- bearerAuth: []/users/{userId}:parameters:- name: userIdin: pathdescription: 用户IDrequired: trueschema:type: integerformat: int64get:tags:- 用户summary: 获取特定用户description: 根据ID获取特定用户的详细信息operationId: getUserByIdresponses:200:description: 成功获取用户信息content:application/json:schema:$ref: #/components/schemas/UserDetailexample:id: 1username: john_doeemail: johnexample.comfirstName: JohnlastName: Doephone: 1234567890status: activecreatedAt: 2023-05-01T12:00:00ZlastLogin: 2023-05-10T08:30:00Z404:description: 用户不存在content:application/json:schema:$ref: #/components/schemas/Errorexample:code: 404message: 用户不存在401:$ref: #/components/responses/UnauthorizedErrorsecurity:- bearerAuth: []put:tags:- 用户summary: 更新用户信息description: 更新特定用户的信息operationId: updateUserrequestBody:description: 更新的用户信息required: truecontent:application/json:schema:$ref: #/components/schemas/UpdateUserexample:firstName: JonathanlastName: Doephone: 1987654321responses:200:description: 用户信息更新成功content:application/json:schema:$ref: #/components/schemas/UserDetail400:description: 无效请求content:application/json:schema:$ref: #/components/schemas/Error404:description: 用户不存在content:application/json:schema:$ref: #/components/schemas/Error401:$ref: #/components/responses/UnauthorizedErrorsecurity:- bearerAuth: []delete:tags:- 用户summary: 删除用户description: 从系统中删除特定用户operationId: deleteUserresponses:204:description: 用户删除成功404:description: 用户不存在content:application/json:schema:$ref: #/components/schemas/Error401:$ref: #/components/responses/UnauthorizedErrorsecurity:- bearerAuth: []/auth/login:post:tags:- 认证summary: 用户登录description: 用户登录并获取访问令牌operationId: loginrequestBody:description: 登录凭证required: truecontent:application/json:schema:type: objectproperties:username:type: stringdescription: 用户名password:type: stringformat: passworddescription: 密码required:- username- passwordexample:username: john_doepassword: password123responses:200:description: 登录成功content:application/json:schema:type: objectproperties:accessToken:type: stringdescription: JWT访问令牌tokenType:type: stringdescription: 令牌类型expiresIn:type: integerdescription: 令牌过期时间秒example:accessToken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...tokenType: BearerexpiresIn: 3600401:description: 登录失败content:application/json:schema:$ref: #/components/schemas/Errorexample:code: 401message: 用户名或密码错误/auth/register:post:tags:- 认证summary: 用户注册description: 注册新用户并获取访问令牌operationId: registerrequestBody:description: 注册信息required: truecontent:application/json:schema:$ref: #/components/schemas/NewUserresponses:201:description: 注册成功content:application/json:schema:type: objectproperties:user:$ref: #/components/schemas/UseraccessToken:type: stringdescription: JWT访问令牌example:user:id: 3username: new_useremail: new_userexample.comstatus: activecreatedAt: 2023-05-10T09:15:00ZaccessToken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...400:description: 无效请求content:application/json:schema:$ref: #/components/schemas/Error409:description: 用户已存在content:application/json:schema:$ref: #/components/schemas/Errorcomponents:schemas:User:type: objectproperties:id:type: integerformat: int64description: 用户唯一标识username:type: stringdescription: 用户名email:type: stringformat: emaildescription: 用户邮箱status:type: stringenum: [active, inactive, banned]description: 用户状态createdAt:type: stringformat: date-timedescription: 创建时间required:- id- username- email- statusUserDetail:allOf:- $ref: #/components/schemas/User- type: objectproperties:firstName:type: stringdescription: 名字lastName:type: stringdescription: 姓氏phone:type: stringdescription: 电话号码lastLogin:type: stringformat: date-timedescription: 最后登录时间NewUser:type: objectproperties:username:type: stringdescription: 用户名minLength: 3maxLength: 50email:type: stringformat: emaildescription: 用户邮箱password:type: stringformat: passworddescription: 用户密码minLength: 8maxLength: 100firstName:type: stringdescription: 名字lastName:type: stringdescription: 姓氏phone:type: stringdescription: 电话号码required:- username- email- passwordUpdateUser:type: objectproperties:email:type: stringformat: emaildescription: 用户邮箱firstName:type: stringdescription: 名字lastName:type: stringdescription: 姓氏phone:type: stringdescription: 电话号码password:type: stringformat: passworddescription: 新密码如需更改minLength: 8maxLength: 100Error:type: objectproperties:code:type: integerformat: int32description: 错误代码message:type: stringdescription: 错误消息required:- code- messageresponses:UnauthorizedError:description: 访问令牌丢失或无效content:application/json:schema:$ref: #/components/schemas/Errorexample:code: 401message: 未授权访问securitySchemes:bearerAuth:type: httpscheme: bearerbearerFormat: JWTdescription: 使用JWT Bearer Token进行身份验证security:- bearerAuth: []下面是文档的主要组成部分1. 基本信息部分API标题和描述用户管理系统的基本功能版本信息1.0.0联系方式API支持团队的联系信息许可证Apache 2.02. 服务器配置生产环境预发布环境开发环境3. API标签分类用户相关操作认证相关操作4. 路径和操作这个API包括以下端点用户管理GET /users- 获取所有用户列表支持分页和筛选POST /users- 创建新用户GET /users/{userId}- 获取特定用户详情PUT /users/{userId}- 更新用户信息DELETE /users/{userId}- 删除用户认证服务POST /auth/login- 用户登录POST /auth/register- 用户注册5. 数据模型User- 基本用户信息UserDetail- 详细用户信息NewUser- 创建用户的请求体UpdateUser- 更新用户的请求体Error- 错误响应6. 安全定义使用 JWT Bearer Token 进行 API 认证。该文档遵循 OpenAPI 3.0.0 规范包含了完整的请求参数、响应状态码、数据模型定义以及示例值。你可以将此 YAML 文档复制到 Swagger Editor 中查看可视化效果或者集成到你的项目中。这个文档可以作为你开发 RESTful API 的基础随着项目发展可以进一步扩展和完善。