实用Swagger JSON配置教程一步步教你打造专业API文档

威震华夏关云长

引言

在当今的软件开发世界中，API（应用程序编程接口）扮演着连接不同软件系统的关键角色。无论是构建微服务架构、移动应用后端，还是第三方集成，良好的API文档都是确保开发者能够轻松理解和使用你的服务的关键。Swagger（现在称为OpenAPI规范）已经成为行业标准，为RESTful API提供了一套强大而灵活的文档框架。

本教程将深入探讨Swagger JSON配置，帮助你从零开始创建专业、全面且易于维护的API文档。无论你是API设计的新手还是有经验的开发者，本指南都将提供实用的步骤和最佳实践，让你的API文档达到专业水平。

Swagger基础

什么是Swagger？

Swagger是一套围绕OpenAPI规范构建的开源工具，用于设计、构建、记录和使用RESTful Web服务。它允许你描述API的结构，以便机器可以读取它们的能力。通过Swagger，你可以：

• 生成交互式API文档
• 自动生成客户端SDK代码
• 进行API测试
• 确保API设计与实现保持一致

OpenAPI规范

OpenAPI规范（OAS）是Swagger的基础，它定义了一个标准的、与语言无关的接口到RESTful API。最新的版本是OpenAPI 3.0，它引入了许多改进和新特性，如：

• 更好的可重用性
• 增强的安全支持
• 改进的内容协商
• 更灵活的回调支持
• 更强的链接支持

环境准备

在开始配置Swagger JSON之前，你需要准备一些工具和环境：

1. 文本编辑器

选择一个支持JSON语法高亮和验证的文本编辑器，如：

• Visual Studio Code
• WebStorm
• Sublime Text
• Atom

2. Swagger编辑器

Swagger提供了在线编辑器，可以帮助你实时预览和验证你的Swagger JSON配置：

Swagger Editor

3. 本地开发环境（可选）

如果你想在本地运行Swagger UI，可以设置一个简单的HTTP服务器：

2. # 使用Node.js的http-server
3. npm install -g http-server
4. http-server -o
6. # 或者使用Python的SimpleHTTPServer
7. python -m http.server 8000

复制代码

创建基本的Swagger JSON配置

让我们从创建一个基本的Swagger JSON配置文件开始。这个文件通常命名为swagger.json或openapi.json。

最小配置示例

2. {
3.   "openapi": "3.0.0",
4.   "info": {
5.     "title": "示例API",
6.     "version": "1.0.0"
7.   },
8.   "paths": {}
9. }

复制代码

这个最小配置包含了三个必需的部分：

1. openapi- 指定使用的OpenAPI规范版本
2. info- 提供API的元数据
3. paths- 定义API的路径和操作

完整的基本配置

让我们扩展这个基本配置，添加更多有用的信息：

2. {
3.   "openapi": "3.0.0",
4.   "info": {
5.     "title": "示例API",
6.     "description": "这是一个示例API，用于演示Swagger JSON配置",
7.     "version": "1.0.0",
8.     "contact": {
9.       "name": "API支持",
10.       "email": "support@example.com",
11.       "url": "https://example.com/support"
12.     },
13.     "license": {
14.       "name": "MIT",
15.       "url": "https://opensource.org/licenses/MIT"
16.     }
17.   },
18.   "servers": [
19.     {
20.       "url": "https://api.example.com/v1",
21.       "description": "生产服务器"
22.     },
23.     {
24.       "url": "https://dev-api.example.com/v1",
25.       "description": "开发服务器"
26.     }
27.   ],
28.   "paths": {}
29. }

复制代码

在这个扩展版本中，我们添加了：

• description- API的详细描述
• contact- 联系信息
• license- 许可证信息
• servers- API服务器列表

深入Swagger JSON结构

现在，让我们深入了解Swagger JSON的各个部分，以及如何配置它们来创建专业的API文档。

Info对象

info对象提供关于API的元数据，它是Swagger JSON的必需部分。以下是一个完整的info对象示例：

2. "info": {
3.   "title": "用户管理API",
4.   "description": "这是一个完整的用户管理系统API，提供用户注册、登录、资料管理等功能。\n\n## 功能特点\n- 用户注册和认证\n- 用户资料管理\n- 角色和权限管理\n- 密码重置\n\n## 使用指南\n要使用此API，开发者需要先注册获取API密钥。",
5.   "termsOfService": "https://example.com/terms",
6.   "contact": {
7.     "name": "API支持团队",
8.     "email": "api-support@example.com",
9.     "url": "https://example.com/contact"
10.   },
11.   "license": {
12.     "name": "Apache 2.0",
13.     "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
14.   },
15.   "version": "1.0.1"
16. }

复制代码

Servers对象

servers数组指定API的目标服务器，可以包含多个环境：

2. "servers": [
3.   {
4.     "url": "https://api.example.com/{version}",
5.     "description": "生产服务器",
6.     "variables": {
7.       "version": {
8.         "default": "v1",
9.         "enum": ["v1", "v2"],
10.         "description": "API版本"
11.       }
12.     }
13.   },
14.   {
15.     "url": "https://dev-api.example.com/v1",
16.     "description": "开发服务器"
17.   },
18.   {
19.     "url": "https://staging-api.example.com/v1",
20.     "description": "预发布服务器"
21.   }
22. ]

复制代码

在这个例子中，我们使用服务器变量来支持API版本控制。

Paths对象

paths对象是Swagger JSON的核心，它定义了API的路径和操作。让我们看一个完整的用户管理API示例：

2. "paths": {
3.   "/users": {
4.     "get": {
5.       "summary": "获取用户列表",
6.       "description": "返回系统中的所有用户列表，支持分页和筛选",
7.       "operationId": "getUsers",
8.       "tags": ["用户管理"],
9.       "parameters": [
10.         {
11.           "name": "page",
12.           "in": "query",
13.           "description": "页码",
14.           "required": false,
15.           "schema": {
16.             "type": "integer",
17.             "default": 1
18.           }
19.         },
20.         {
21.           "name": "limit",
22.           "in": "query",
23.           "description": "每页记录数",
24.           "required": false,
25.           "schema": {
26.             "type": "integer",
27.             "default": 20,
28.             "maximum": 100
29.           }
30.         },
31.         {
32.           "name": "role",
33.           "in": "query",
34.           "description": "按角色筛选",
35.           "required": false,
36.           "schema": {
37.             "type": "string",
38.             "enum": ["admin", "user", "guest"]
39.           }
40.         }
41.       ],
42.       "responses": {
43.         "200": {
44.           "description": "成功获取用户列表",
45.           "content": {
46.             "application/json": {
47.               "schema": {
48.                 "type": "object",
49.                 "properties": {
50.                   "users": {
51.                     "type": "array",
52.                     "items": {
53.                       "$ref": "#/components/schemas/User"
54.                     }
55.                   },
56.                   "pagination": {
57.                     "$ref": "#/components/schemas/Pagination"
58.                   }
59.                 }
60.               }
61.             }
62.           }
63.         },
64.         "401": {
65.           "description": "未授权"
66.         },
67.         "403": {
68.           "description": "禁止访问"
69.         }
70.       },
71.       "security": [
72.         {
73.           "bearerAuth": []
74.         }
75.       ]
76.     },
77.     "post": {
78.       "summary": "创建新用户",
79.       "description": "在系统中创建一个新用户",
80.       "operationId": "createUser",
81.       "tags": ["用户管理"],
82.       "requestBody": {
83.         "required": true,
84.         "content": {
85.           "application/json": {
86.             "schema": {
87.               "$ref": "#/components/schemas/NewUser"
88.             }
89.           }
90.         }
91.       },
92.       "responses": {
93.         "201": {
94.           "description": "用户创建成功",
95.           "content": {
96.             "application/json": {
97.               "schema": {
98.                 "$ref": "#/components/schemas/User"
99.               }
100.             }
101.           }
102.         },
103.         "400": {
104.           "description": "无效的输入数据"
105.         },
106.         "409": {
107.           "description": "用户已存在"
108.         }
109.       },
110.       "security": [
111.         {
112.           "bearerAuth": []
113.         }
114.       ]
115.     }
116.   },
117.   "/users/{userId}": {
118.     "get": {
119.       "summary": "获取用户详情",
120.       "description": "根据用户ID获取用户详细信息",
121.       "operationId": "getUserById",
122.       "tags": ["用户管理"],
123.       "parameters": [
124.         {
125.           "name": "userId",
126.           "in": "path",
127.           "required": true,
128.           "description": "用户ID",
129.           "schema": {
130.             "type": "string",
131.             "format": "uuid"
132.           }
133.         }
134.       ],
135.       "responses": {
136.         "200": {
137.           "description": "成功获取用户详情",
138.           "content": {
139.             "application/json": {
140.               "schema": {
141.                 "$ref": "#/components/schemas/User"
142.               }
143.             }
144.           }
145.         },
146.         "404": {
147.           "description": "用户不存在"
148.         }
149.       },
150.       "security": [
151.         {
152.           "bearerAuth": []
153.         }
154.       ]
155.     },
156.     "put": {
157.       "summary": "更新用户信息",
158.       "description": "更新指定用户的信息",
159.       "operationId": "updateUser",
160.       "tags": ["用户管理"],
161.       "parameters": [
162.         {
163.           "name": "userId",
164.           "in": "path",
165.           "required": true,
166.           "description": "用户ID",
167.           "schema": {
168.             "type": "string",
169.             "format": "uuid"
170.           }
171.         }
172.       ],
173.       "requestBody": {
174.         "required": true,
175.         "content": {
176.           "application/json": {
177.             "schema": {
178.               "$ref": "#/components/schemas/UpdateUser"
179.             }
180.           }
181.         }
182.       },
183.       "responses": {
184.         "200": {
185.           "description": "用户更新成功",
186.           "content": {
187.             "application/json": {
188.               "schema": {
189.                 "$ref": "#/components/schemas/User"
190.               }
191.             }
192.           }
193.         },
194.         "400": {
195.           "description": "无效的输入数据"
196.         },
197.         "404": {
198.           "description": "用户不存在"
199.         }
200.       },
201.       "security": [
202.         {
203.           "bearerAuth": []
204.         }
205.       ]
206.     },
207.     "delete": {
208.       "summary": "删除用户",
209.       "description": "从系统中删除指定用户",
210.       "operationId": "deleteUser",
211.       "tags": ["用户管理"],
212.       "parameters": [
213.         {
214.           "name": "userId",
215.           "in": "path",
216.           "required": true,
217.           "description": "用户ID",
218.           "schema": {
219.             "type": "string",
220.             "format": "uuid"
221.           }
222.         }
223.       ],
224.       "responses": {
225.         "204": {
226.           "description": "用户删除成功"
227.         },
228.         "404": {
229.           "description": "用户不存在"
230.         }
231.       },
232.       "security": [
233.         {
234.           "bearerAuth": []
235.         }
236.       ]
237.     }
238.   }
239. }

复制代码

这个示例展示了如何定义完整的CRUD操作，包括：

• 路径参数（userId）
• 查询参数（page,limit,role）
• 请求体（用于创建和更新用户）
• 响应定义（包括成功和错误响应）
• 安全要求（使用Bearer认证）

定义数据模型

在Swagger JSON中，数据模型在components.schemas部分定义。这些模型可以被路径和响应引用，确保API文档的一致性和可维护性。

基本数据模型

让我们为用户管理API定义一些基本的数据模型：

2. "components": {
3.   "schemas": {
4.     "User": {
5.       "type": "object",
6.       "required": ["id", "username", "email", "role"],
7.       "properties": {
8.         "id": {
9.           "type": "string",
10.           "format": "uuid",
11.           "description": "用户唯一标识符",
12.           "readOnly": true,
13.           "example": "550e8400-e29b-41d4-a716-446655440000"
14.         },
15.         "username": {
16.           "type": "string",
17.           "description": "用户名",
18.           "minLength": 3,
19.           "maxLength": 30,
20.           "pattern": "^[a-zA-Z0-9_-]+$",
21.           "example": "johndoe"
22.         },
23.         "email": {
24.           "type": "string",
25.           "format": "email",
26.           "description": "用户电子邮箱",
27.           "example": "john.doe@example.com"
28.         },
29.         "firstName": {
30.           "type": "string",
31.           "description": "名字",
32.           "example": "John"
33.         },
34.         "lastName": {
35.           "type": "string",
36.           "description": "姓氏",
37.           "example": "Doe"
38.         },
39.         "role": {
40.           "type": "string",
41.           "description": "用户角色",
42.           "enum": ["admin", "user", "guest"],
43.           "example": "user"
44.         },
45.         "createdAt": {
46.           "type": "string",
47.           "format": "date-time",
48.           "description": "创建时间",
49.           "readOnly": true,
50.           "example": "2023-01-01T00:00:00Z"
51.         },
52.         "updatedAt": {
53.           "type": "string",
54.           "format": "date-time",
55.           "description": "更新时间",
56.           "readOnly": true,
57.           "example": "2023-01-01T00:00:00Z"
58.         }
59.       }
60.     },
61.     "NewUser": {
62.       "type": "object",
63.       "required": ["username", "email", "password"],
64.       "properties": {
65.         "username": {
66.           "type": "string",
67.           "description": "用户名",
68.           "minLength": 3,
69.           "maxLength": 30,
70.           "pattern": "^[a-zA-Z0-9_-]+$",
71.           "example": "johndoe"
72.         },
73.         "email": {
74.           "type": "string",
75.           "format": "email",
76.           "description": "用户电子邮箱",
77.           "example": "john.doe@example.com"
78.         },
79.         "password": {
80.           "type": "string",
81.           "format": "password",
82.           "description": "密码",
83.           "minLength": 8,
84.           "writeOnly": true,
85.           "example": "SecurePassword123!"
86.         },
87.         "firstName": {
88.           "type": "string",
89.           "description": "名字",
90.           "example": "John"
91.         },
92.         "lastName": {
93.           "type": "string",
94.           "description": "姓氏",
95.           "example": "Doe"
96.         }
97.       }
98.     },
99.     "UpdateUser": {
100.       "type": "object",
101.       "properties": {
102.         "email": {
103.           "type": "string",
104.           "format": "email",
105.           "description": "用户电子邮箱",
106.           "example": "john.doe@example.com"
107.         },
108.         "firstName": {
109.           "type": "string",
110.           "description": "名字",
111.           "example": "John"
112.         },
113.         "lastName": {
114.           "type": "string",
115.           "description": "姓氏",
116.           "example": "Doe"
117.         },
118.         "role": {
119.           "type": "string",
120.           "description": "用户角色",
121.           "enum": ["admin", "user", "guest"],
122.           "example": "user"
123.         }
124.       }
125.     },
126.     "Pagination": {
127.       "type": "object",
128.       "properties": {
129.         "page": {
130.           "type": "integer",
131.           "description": "当前页码",
132.           "example": 1
133.         },
134.         "limit": {
135.           "type": "integer",
136.           "description": "每页记录数",
137.           "example": 20
138.         },
139.         "total": {
140.           "type": "integer",
141.           "description": "总记录数",
142.           "example": 100
143.         },
144.         "pages": {
145.           "type": "integer",
146.           "description": "总页数",
147.           "example": 5
148.         }
149.       }
150.     },
151.     "Error": {
152.       "type": "object",
153.       "required": ["code", "message"],
154.       "properties": {
155.         "code": {
156.           "type": "integer",
157.           "description": "错误代码",
158.           "example": 400
159.         },
160.         "message": {
161.           "type": "string",
162.           "description": "错误消息",
163.           "example": "Invalid input data"
164.         },
165.         "details": {
166.           "type": "array",
167.           "items": {
168.             "type": "string"
169.           },
170.           "description": "错误详情",
171.           "example": ["Username is required", "Email must be a valid email address"]
172.         }
173.       }
174.     }
175.   }
176. }

复制代码

这些数据模型展示了Swagger JSON中模式定义的各种特性：

1. 基本类型和格式：如string、integer、date-time、email、uuid等
2. 验证规则：如required、minLength、maxLength、pattern等
3. 枚举值：使用enum限制字段的可能值
4. 只读和只写字段：使用readOnly和writeOnly标记
5. 引用：使用$ref引用其他模式
6. 示例值：使用example提供示例数据

复杂数据模型

对于更复杂的场景，你可以定义嵌套对象、数组、多态类型等。以下是一个示例：

2. "components": {
3.   "schemas": {
4.     "Order": {
5.       "type": "object",
6.       "required": ["id", "customer", "items", "total", "status"],
7.       "properties": {
8.         "id": {
9.           "type": "string",
10.           "format": "uuid",
11.           "description": "订单ID",
12.           "readOnly": true
13.         },
14.         "customer": {
15.           "$ref": "#/components/schemas/Customer"
16.         },
17.         "items": {
18.           "type": "array",
19.           "description": "订单项目",
20.           "items": {
21.             "$ref": "#/components/schemas/OrderItem"
22.           }
23.         },
24.         "shippingAddress": {
25.           "oneOf": [
26.             {
27.               "$ref": "#/components/schemas/Address"
28.             },
29.             {
30.               "type": "null"
31.             }
32.           ],
33.           "description": "配送地址"
34.         },
35.         "billingAddress": {
36.           "$ref": "#/components/schemas/Address"
37.         },
38.         "payment": {
39.           "oneOf": [
40.             {
41.               "$ref": "#/components/schemas/CreditCardPayment"
42.             },
43.             {
44.               "$ref": "#/components/schemas/PayPalPayment"
45.             }
46.           ],
47.           "discriminator": {
48.             "propertyName": "type",
49.             "mapping": {
50.               "credit_card": "#/components/schemas/CreditCardPayment",
51.               "paypal": "#/components/schemas/PayPalPayment"
52.             }
53.           }
54.         },
55.         "total": {
56.           "type": "number",
57.           "format": "decimal",
58.           "description": "订单总金额",
59.           "minimum": 0
60.         },
61.         "status": {
62.           "type": "string",
63.           "description": "订单状态",
64.           "enum": ["pending", "processing", "shipped", "delivered", "cancelled"],
65.           "default": "pending"
66.         },
67.         "createdAt": {
68.           "type": "string",
69.           "format": "date-time",
70.           "description": "创建时间",
71.           "readOnly": true
72.         },
73.         "updatedAt": {
74.           "type": "string",
75.           "format": "date-time",
76.           "description": "更新时间",
77.           "readOnly": true
78.         }
79.       }
80.     },
81.     "OrderItem": {
82.       "type": "object",
83.       "required": ["product", "quantity", "price"],
84.       "properties": {
85.         "product": {
86.           "$ref": "#/components/schemas/Product"
87.         },
88.         "quantity": {
89.           "type": "integer",
90.           "description": "数量",
91.           "minimum": 1
92.         },
93.         "price": {
94.           "type": "number",
95.           "format": "decimal",
96.           "description": "单价",
97.           "minimum": 0
98.         }
99.       }
100.     },
101.     "Customer": {
102.       "type": "object",
103.       "required": ["id", "name", "email"],
104.       "properties": {
105.         "id": {
106.           "type": "string",
107.           "format": "uuid",
108.           "description": "客户ID"
109.         },
110.         "name": {
111.           "type": "string",
112.           "description": "客户姓名"
113.         },
114.         "email": {
115.           "type": "string",
116.           "format": "email",
117.           "description": "客户邮箱"
118.         },
119.         "phone": {
120.           "type": "string",
121.           "description": "客户电话"
122.         }
123.       }
124.     },
125.     "Address": {
126.       "type": "object",
127.       "required": ["street", "city", "country"],
128.       "properties": {
129.         "street": {
130.           "type": "string",
131.           "description": "街道地址"
132.         },
133.         "city": {
134.           "type": "string",
135.           "description": "城市"
136.         },
137.         "state": {
138.           "type": "string",
139.           "description": "州/省"
140.         },
141.         "postalCode": {
142.           "type": "string",
143.           "description": "邮政编码"
144.         },
145.         "country": {
146.           "type": "string",
147.           "description": "国家"
148.         }
149.       }
150.     },
151.     "CreditCardPayment": {
152.       "type": "object",
153.       "required": ["type", "cardNumber", "expiryDate", "cvv"],
154.       "properties": {
155.         "type": {
156.           "type": "string",
157.           "enum": ["credit_card"]
158.         },
159.         "cardNumber": {
160.           "type": "string",
161.           "description": "信用卡号",
162.           "pattern": "^[0-9]{16}$",
163.           "writeOnly": true
164.         },
165.         "expiryDate": {
166.           "type": "string",
167.           "description": "有效期",
168.           "pattern": "^[0-9]{2}/[0-9]{2}$",
169.           "writeOnly": true
170.         },
171.         "cvv": {
172.           "type": "string",
173.           "description": "CVV码",
174.           "pattern": "^[0-9]{3,4}$",
175.           "writeOnly": true
176.         },
177.         "cardholderName": {
178.           "type": "string",
179.           "description": "持卡人姓名",
180.           "writeOnly": true
181.         }
182.       }
183.     },
184.     "PayPalPayment": {
185.       "type": "object",
186.       "required": ["type", "email"],
187.       "properties": {
188.         "type": {
189.           "type": "string",
190.           "enum": ["paypal"]
191.         },
192.         "email": {
193.           "type": "string",
194.           "format": "email",
195.           "description": "PayPal账户邮箱"
196.         }
197.       }
198.     }
199.   }
200. }

复制代码

这个复杂示例展示了：

1. 嵌套对象：Order包含Customer、Address等嵌套对象
2. 数组：Order.items是一个OrderItem对象的数组
3. 多态类型：使用oneOf定义多种可能的类型
4. 判别器：使用discriminator区分多态类型
5. 条件字段：使用oneOf与null类型组合定义可选字段

添加安全配置

API安全是现代应用程序的关键部分。Swagger JSON提供了多种方式来描述API的安全要求。

定义安全方案

在components.securitySchemes部分定义可用的安全方案：

2. "components": {
3.   "securitySchemes": {
4.     "bearerAuth": {
5.       "type": "http",
6.       "scheme": "bearer",
7.       "bearerFormat": "JWT",
8.       "description": "JWT Token认证"
9.     },
10.     "basicAuth": {
11.       "type": "http",
12.       "scheme": "basic",
13.       "description": "基本认证"
14.     },
15.     "apiKey": {
16.       "type": "apiKey",
17.       "in": "header",
18.       "name": "X-API-Key",
19.       "description": "API密钥认证"
20.     },
21.     "oauth2": {
22.       "type": "oauth2",
23.       "flows": {
24.         "authorizationCode": {
25.           "authorizationUrl": "https://example.com/oauth/authorize",
26.           "tokenUrl": "https://example.com/oauth/token",
27.           "scopes": {
28.             "read": "读取权限",
29.             "write": "写入权限"
30.           }
31.         },
32.         "implicit": {
33.           "authorizationUrl": "https://example.com/oauth/authorize",
34.           "scopes": {
35.             "read": "读取权限",
36.             "write": "写入权限"
37.           }
38.         },
39.         "password": {
40.           "tokenUrl": "https://example.com/oauth/token",
41.           "scopes": {
42.             "read": "读取权限",
43.             "write": "写入权限"
44.           }
45.         },
46.         "clientCredentials": {
47.           "tokenUrl": "https://example.com/oauth/token",
48.           "scopes": {
49.             "read": "读取权限",
50.             "write": "写入权限"
51.           }
52.         }
53.       }
54.     }
55.   }
56. }

复制代码

这个示例定义了四种常见的安全方案：

1. Bearer认证：通常用于JWT令牌
2. 基本认证：用户名和密码
3. API密钥：在头部传递的API密钥
4. OAuth2：包括授权码、隐式、密码和客户端凭据流程

应用安全要求

在API操作上应用安全要求：

2. "paths": {
3.   "/users": {
4.     "get": {
5.       "summary": "获取用户列表",
6.       "security": [
7.         {
8.           "bearerAuth": []
9.         },
10.         {
11.           "apiKey": []
12.         }
13.       ],
14.       // 其他操作定义...
15.     },
16.     "post": {
17.       "summary": "创建用户",
18.       "security": [
19.         {
20.           "bearerAuth": []
21.         }
22.       ],
23.       // 其他操作定义...
24.     }
25.   },
26.   "/public/info": {
27.     "get": {
28.       "summary": "获取公开信息",
29.       // 没有security属性，表示不需要认证
30.       // 其他操作定义...
31.     }
32.   }
33. }

复制代码

在这个示例中：

• /users的GET操作支持Bearer认证或API密钥认证
• /users的POST操作只支持Bearer认证
• /public/info不需要认证

全局安全要求

你还可以在根级别定义全局安全要求，应用于所有API操作：

2. {
3.   "openapi": "3.0.0",
4.   "info": {
5.     "title": "示例API",
6.     "version": "1.0.0"
7.   },
8.   "security": [
9.     {
10.       "bearerAuth": []
11.     }
12.   ],
13.   "paths": {
14.     // 路径定义...
15.   }
16. }

复制代码

然后，对于不需要认证的操作，可以使用空数组覆盖全局安全要求：

2. "/public/info": {
3.   "get": {
4.     "summary": "获取公开信息",
5.     "security": [],
6.     // 其他操作定义...
7.   }
8. }

复制代码

高级配置技巧

自定义UI配置

Swagger UI可以通过swagger-ui扩展进行自定义：

2. {
3.   "openapi": "3.0.0",
4.   "info": {
5.     "title": "示例API",
6.     "version": "1.0.0"
7.   },
8.   "paths": {},
9.   "x-swagger-ui": {
10.     "filter": true,
11.     "displayRequestDuration": true,
12.     "docExpansion": "none",
13.     "defaultModelsExpandDepth": -1,
14.     "defaultModelExpandDepth": 1,
15.     "displayOperationId": true,
16.     "showExtensions": true,
17.     "showCommonExtensions": true,
18.     "supportedSubmitMethods": ["get", "post", "put", "delete"],
19.     "validatorUrl": "https://validator.swagger.io"
20.   }
21. }

复制代码

标签分组

使用标签对API操作进行分组，提高文档的可读性：

2. {
3.   "openapi": "3.0.0",
4.   "info": {
5.     "title": "示例API",
6.     "version": "1.0.0"
7.   },
8.   "tags": [
9.     {
10.       "name": "用户管理",
11.       "description": "用户相关的操作"
12.     },
13.     {
14.       "name": "产品管理",
15.       "description": "产品相关的操作"
16.     },
17.     {
18.       "name": "订单管理",
19.       "description": "订单相关的操作"
20.     }
21.   ],
22.   "paths": {
23.     "/users": {
24.       "get": {
25.         "tags": ["用户管理"],
26.         "summary": "获取用户列表",
27.         // 其他操作定义...
28.       }
29.     },
30.     "/products": {
31.       "get": {
32.         "tags": ["产品管理"],
33.         "summary": "获取产品列表",
34.         // 其他操作定义...
35.       }
36.     },
37.     "/orders": {
38.       "get": {
39.         "tags": ["订单管理"],
40.         "summary": "获取订单列表",
41.         // 其他操作定义...
42.       }
43.     }
44.   }
45. }

复制代码

外部文档引用

使用externalDocs引用外部文档：

2. {
3.   "openapi": "3.0.0",
4.   "info": {
5.     "title": "示例API",
6.     "version": "1.0.0",
7.     "externalDocs": {
8.       "description": "完整文档",
9.       "url": "https://docs.example.com"
10.     }
11.   },
12.   "paths": {
13.     "/users": {
14.       "get": {
15.         "summary": "获取用户列表",
16.         "externalDocs": {
17.           "description": "用户管理指南",
18.           "url": "https://docs.example.com/user-management"
19.         },
20.         // 其他操作定义...
21.       }
22.     }
23.   }
24. }

复制代码

示例值和示例请求/响应

为参数、请求体和响应添加示例值：

2. "paths": {
3.   "/users": {
4.     "post": {
5.       "summary": "创建用户",
6.       "requestBody": {
7.         "required": true,
8.         "content": {
9.           "application/json": {
10.             "schema": {
11.               "$ref": "#/components/schemas/NewUser"
12.             },
13.             "example": {
14.               "username": "johndoe",
15.               "email": "john.doe@example.com",
16.               "password": "SecurePassword123!",
17.               "firstName": "John",
18.               "lastName": "Doe"
19.             }
20.           }
21.         }
22.       },
23.       "responses": {
24.         "201": {
25.           "description": "用户创建成功",
26.           "content": {
27.             "application/json": {
28.               "schema": {
29.                 "$ref": "#/components/schemas/User"
30.               },
31.               "examples": {
32.                 "successExample": {
33.                   "summary": "成功示例",
34.                   "value": {
35.                     "id": "550e8400-e29b-41d4-a716-446655440000",
36.                     "username": "johndoe",
37.                     "email": "john.doe@example.com",
38.                     "firstName": "John",
39.                     "lastName": "Doe",
40.                     "role": "user",
41.                     "createdAt": "2023-01-01T00:00:00Z",
42.                     "updatedAt": "2023-01-01T00:00:00Z"
43.                   }
44.                 }
45.               }
46.             }
47.           }
48.         }
49.       }
50.     }
51.   }
52. }

复制代码

回调定义

对于需要回调的API（如webhooks），可以使用callbacks定义：

2. "paths": {
3.   "/subscriptions": {
4.     "post": {
5.       "summary": "创建订阅",
6.       "requestBody": {
7.         "required": true,
8.         "content": {
9.           "application/json": {
10.             "schema": {
11.               "$ref": "#/components/schemas/Subscription"
12.             }
13.           }
14.         }
15.       },
16.       "responses": {
17.         "201": {
18.           "description": "订阅创建成功"
19.         }
20.       },
21.       "callbacks": {
22.         "eventCallback": {
23.           "{$request.body#/callbackUrl}": {
24.             "post": {
25.               "summary": "事件回调",
26.               "requestBody": {
27.                 "required": true,
28.                 "content": {
29.                   "application/json": {
30.                     "schema": {
31.                       "$ref": "#/components/schemas/Event"
32.                     }
33.                   }
34.                 }
35.               },
36.               "responses": {
37.                 "200": {
38.                   "description": "回调处理成功"
39.                 }
40.               }
41.             }
42.           }
43.         }
44.       }
45.     }
46.   }
47. }

复制代码

常见问题与解决方案

1. 如何处理版本控制？

问题：随着API的发展，如何处理不同版本的API文档？

解决方案：

2. {
3.   "openapi": "3.0.0",
4.   "info": {
5.     "title": "示例API",
6.     "version": "1.0.0",
7.     "description": "这是API的v1版本文档。v2版本文档请访问：https://api.example.com/v2/docs"
8.   },
9.   "servers": [
10.     {
11.       "url": "https://api.example.com/v1",
12.       "description": "API v1"
13.     }
14.   ],
15.   "paths": {}
16. }

复制代码

或者使用服务器变量：

2. {
3.   "openapi": "3.0.0",
4.   "info": {
5.     "title": "示例API",
6.     "version": "1.0.0"
7.   },
8.   "servers": [
9.     {
10.       "url": "https://api.example.com/{version}",
11.       "description": "API服务器",
12.       "variables": {
13.         "version": {
14.           "default": "v1",
15.           "enum": ["v1", "v2"],
16.           "description": "API版本"
17.         }
18.       }
19.     }
20.   ],
21.   "paths": {}
22. }

复制代码

2. 如何处理分页？

问题：如何为分页API创建清晰的文档？

解决方案：

2. "paths": {
3.   "/users": {
4.     "get": {
5.       "summary": "获取用户列表",
6.       "parameters": [
7.         {
8.           "name": "page",
9.           "in": "query",
10.           "description": "页码",
11.           "required": false,
12.           "schema": {
13.             "type": "integer",
14.             "default": 1,
15.             "minimum": 1
16.           }
17.         },
18.         {
19.           "name": "limit",
20.           "in": "query",
21.           "description": "每页记录数",
22.           "required": false,
23.           "schema": {
24.             "type": "integer",
25.             "default": 20,
26.             "minimum": 1,
27.             "maximum": 100
28.           }
29.         },
30.         {
31.           "name": "sort",
32.           "in": "query",
33.           "description": "排序字段",
34.           "required": false,
35.           "schema": {
36.             "type": "string",
37.             "enum": ["id", "username", "email", "createdAt"],
38.             "default": "id"
39.           }
40.         },
41.         {
42.           "name": "order",
43.           "in": "query",
44.           "description": "排序方向",
45.           "required": false,
46.           "schema": {
47.             "type": "string",
48.             "enum": ["asc", "desc"],
49.             "default": "asc"
50.           }
51.         }
52.       ],
53.       "responses": {
54.         "200": {
55.           "description": "成功获取用户列表",
56.           "content": {
57.             "application/json": {
58.               "schema": {
59.                 "type": "object",
60.                 "properties": {
61.                   "data": {
62.                     "type": "array",
63.                     "items": {
64.                       "$ref": "#/components/schemas/User"
65.                     }
66.                   },
67.                   "pagination": {
68.                     "type": "object",
69.                     "properties": {
70.                       "page": {
71.                         "type": "integer",
72.                         "example": 1
73.                       },
74.                       "limit": {
75.                         "type": "integer",
76.                         "example": 20
77.                       },
78.                       "total": {
79.                         "type": "integer",
80.                         "example": 100
81.                       },
82.                       "pages": {
83.                         "type": "integer",
84.                         "example": 5
85.                       }
86.                     }
87.                   }
88.                 }
89.               }
90.             }
91.           }
92.         }
93.       }
94.     }
95.   }
96. }

复制代码

3. 如何处理文件上传？

问题：如何为文件上传API创建文档？

解决方案：

2. "paths": {
3.   "/files": {
4.     "post": {
5.       "summary": "上传文件",
6.       "requestBody": {
7.         "required": true,
8.         "content": {
9.           "multipart/form-data": {
10.             "schema": {
11.               "type": "object",
12.               "properties": {
13.                 "file": {
14.                   "type": "string",
15.                   "format": "binary",
16.                   "description": "要上传的文件"
17.                 },
18.                 "description": {
19.                   "type": "string",
20.                   "description": "文件描述"
21.                 },
22.                 "tags": {
23.                   "type": "array",
24.                   "items": {
25.                     "type": "string"
26.                   },
27.                   "description": "文件标签"
28.                 }
29.               }
30.             }
31.           }
32.         }
33.       },
34.       "responses": {
35.         "201": {
36.           "description": "文件上传成功",
37.           "content": {
38.             "application/json": {
39.               "schema": {
40.                 "$ref": "#/components/schemas/File"
41.               }
42.             }
43.           }
44.         }
45.       }
46.     }
47.   }
48. }

复制代码

4. 如何处理错误响应？

问题：如何为API错误创建一致的文档？

解决方案：

首先，定义一个通用的错误响应模式：

2. "components": {
3.   "schemas": {
4.     "Error": {
5.       "type": "object",
6.       "required": ["code", "message"],
7.       "properties": {
8.         "code": {
9.           "type": "integer",
10.           "description": "错误代码",
11.           "example": 400
12.         },
13.         "message": {
14.           "type": "string",
15.           "description": "错误消息",
16.           "example": "Invalid input data"
17.         },
18.         "details": {
19.           "type": "array",
20.           "items": {
21.             "type": "string"
22.           },
23.           "description": "错误详情",
24.           "example": ["Username is required", "Email must be a valid email address"]
25.         },
26.         "timestamp": {
27.           "type": "string",
28.           "format": "date-time",
29.           "description": "错误发生时间",
30.           "readOnly": true
31.         },
32.         "path": {
33.           "type": "string",
34.           "description": "请求路径",
35.           "readOnly": true
36.         }
37.       }
38.     }
39.   }
40. }

复制代码

然后，在API操作中引用这个模式：

2. "paths": {
3.   "/users": {
4.     "post": {
5.       "summary": "创建用户",
6.       "requestBody": {
7.         "required": true,
8.         "content": {
9.           "application/json": {
10.             "schema": {
11.               "$ref": "#/components/schemas/NewUser"
12.             }
13.           }
14.         }
15.       },
16.       "responses": {
17.         "201": {
18.           "description": "用户创建成功",
19.           "content": {
20.             "application/json": {
21.               "schema": {
22.                 "$ref": "#/components/schemas/User"
23.               }
24.             }
25.           }
26.         },
27.         "400": {
28.           "description": "无效的输入数据",
29.           "content": {
30.             "application/json": {
31.               "schema": {
32.                 "$ref": "#/components/schemas/Error"
33.               },
34.               "examples": {
35.                 "validationError": {
36.                   "summary": "验证错误示例",
37.                   "value": {
38.                     "code": 400,
39.                     "message": "Invalid input data",
40.                     "details": [
41.                       "Username is required",
42.                       "Email must be a valid email address"
43.                     ],
44.                     "timestamp": "2023-01-01T00:00:00Z",
45.                     "path": "/users"
46.                   }
47.                 }
48.               }
49.             }
50.           }
51.         },
52.         "409": {
53.           "description": "用户已存在",
54.           "content": {
55.             "application/json": {
56.               "schema": {
57.                 "$ref": "#/components/schemas/Error"
58.               },
59.               "examples": {
60.                 "conflictError": {
61.                   "summary": "冲突错误示例",
62.                   "value": {
63.                     "code": 409,
64.                     "message": "User already exists",
65.                     "details": [
66.                       "A user with the same username or email already exists"
67.                     ],
68.                     "timestamp": "2023-01-01T00:00:00Z",
69.                     "path": "/users"
70.                   }
71.                 }
72.               }
73.             }
74.           }
75.         }
76.       }
77.     }
78.   }
79. }

复制代码

5. 如何处理复杂查询参数？

问题：如何为带有复杂查询参数的API创建文档？

解决方案：

2. "paths": {
3.   "/users": {
4.     "get": {
5.       "summary": "获取用户列表",
6.       "parameters": [
7.         {
8.           "name": "filter",
9.           "in": "query",
10.           "description": "筛选条件",
11.           "required": false,
12.           "schema": {
13.             "type": "object",
14.             "properties": {
15.               "role": {
16.                 "type": "string",
17.                 "enum": ["admin", "user", "guest"]
18.               },
19.               "status": {
20.                 "type": "string",
21.                 "enum": ["active", "inactive", "pending"]
22.               },
23.               "createdAt": {
24.                 "type": "object",
25.                 "properties": {
26.                   "from": {
27.                     "type": "string",
28.                     "format": "date-time"
29.                   },
30.                   "to": {
31.                     "type": "string",
32.                     "format": "date-time"
33.                   }
34.                 }
35.               }
36.             }
37.           },
38.           "example": {
39.             "role": "user",
40.             "status": "active",
41.             "createdAt": {
42.               "from": "2023-01-01T00:00:00Z",
43.               "to": "2023-01-31T23:59:59Z"
44.             }
45.           }
46.         },
47.         {
48.           "name": "fields",
49.           "in": "query",
50.           "description": "返回字段",
51.           "required": false,
52.           "schema": {
53.             "type": "array",
54.             "items": {
55.               "type": "string",
56.               "enum": ["id", "username", "email", "firstName", "lastName", "role", "createdAt"]
57.             }
58.           },
59.           "example": ["id", "username", "email"]
60.         },
61.         {
62.           "name": "include",
63.           "in": "query",
64.           "description": "包含关联资源",
65.           "required": false,
66.           "schema": {
67.             "type": "array",
68.             "items": {
69.               "type": "string",
70.               "enum": ["profile", "settings", "permissions"]
71.             }
72.           },
73.           "example": ["profile"]
74.         }
75.       ],
76.       "responses": {
77.         "200": {
78.           "description": "成功获取用户列表",
79.           "content": {
80.             "application/json": {
81.               "schema": {
82.                 "type": "object",
83.                 "properties": {
84.                   "data": {
85.                     "type": "array",
86.                     "items": {
87.                       "$ref": "#/components/schemas/User"
88.                     }
89.                   },
90.                   "included": {
91.                     "type": "array",
92.                     "items": {
93.                       "oneOf": [
94.                         {
95.                           "$ref": "#/components/schemas/Profile"
96.                         },
97.                         {
98.                           "$ref": "#/components/schemas/Settings"
99.                         },
100.                         {
101.                           "$ref": "#/components/schemas/Permission"
102.                         }
103.                       ]
104.                     }
105.                   }
106.                 }
107.               }
108.             }
109.           }
110.         }
111.       }
112.     }
113.   }
114. }

复制代码

最佳实践

1. 保持一致性

在整个API文档中保持一致的命名约定、结构和格式。例如：

• 使用一致的命名约定（如camelCase或snake_case）
• 为所有错误响应使用相同的结构
• 为所有分页响应使用相同的结构
• 为所有时间字段使用相同的格式

2. 提供清晰的描述

为所有API组件提供清晰、简洁的描述：

2. {
3.   "openapi": "3.0.0",
4.   "info": {
5.     "title": "用户管理API",
6.     "description": "提供用户注册、认证和管理的完整功能。\n\n## 认证\n此API使用Bearer Token（JWT）进行认证。请在请求头中包含`Authorization: Bearer <token>`。\n\n## 错误处理\nAPI使用标准HTTP状态码表示请求的成功或失败。错误响应包含以下结构：\n\n```json\n{\n  "code": 400,\n  "message": "错误描述",\n  "details": ["详细错误信息"],\n  "timestamp": "2023-01-01T00:00:00Z",\n  "path": "/api/path"\n}\n```",
7.     "version": "1.0.0"
8.   }
9. }

复制代码

3. 使用示例

为所有参数、请求体和响应提供有意义的示例：

2. "components": {
3.   "schemas": {
4.     "User": {
5.       "type": "object",
6.       "required": ["id", "username", "email"],
7.       "properties": {
8.         "id": {
9.           "type": "string",
10.           "format": "uuid",
11.           "description": "用户唯一标识符",
12.           "example": "550e8400-e29b-41d4-a716-446655440000"
13.         },
14.         "username": {
15.           "type": "string",
16.           "description": "用户名",
17.           "minLength": 3,
18.           "maxLength": 30,
19.           "example": "johndoe"
20.         },
21.         "email": {
22.           "type": "string",
23.           "format": "email",
24.           "description": "用户电子邮箱",
25.           "example": "john.doe@example.com"
26.         }
27.       }
28.     }
29.   }
30. }

复制代码

4. 使用引用

使用$ref引用重复使用的组件，减少冗余并提高可维护性：

2. "components": {
3.   "schemas": {
4.     "User": {
5.       "type": "object",
6.       "properties": {
7.         "id": {
8.           "type": "string",
9.           "format": "uuid"
10.         },
11.         "username": {
12.           "type": "string"
13.         },
14.         "email": {
15.           "type": "string",
16.           "format": "email"
17.         }
18.       }
19.     },
20.     "NewUser": {
21.       "allOf": [
22.         {
23.           "type": "object",
24.           "required": ["username", "email", "password"],
25.           "properties": {
26.             "password": {
27.               "type": "string",
28.               "format": "password",
29.               "minLength": 8
30.             }
31.           }
32.         },
33.         {
34.           "$ref": "#/components/schemas/User"
35.         }
36.       ]
37.     }
38.   }
39. }

复制代码

5. 验证你的Swagger JSON

使用Swagger编辑器或其他验证工具确保你的Swagger JSON有效：

2. {
3.   "openapi": "3.0.0",
4.   "info": {
5.     "title": "示例API",
6.     "version": "1.0.0"
7.   },
8.   "paths": {}
9. }

复制代码

6. 使用扩展

使用OpenAPI扩展添加自定义元数据：

2. {
3.   "openapi": "3.0.0",
4.   "info": {
5.     "title": "示例API",
6.     "version": "1.0.0",
7.     "x-api-id": "12345",
8.     "x-status": "active",
9.     "x-contact": {
10.       "name": "API团队",
11.       "email": "api@example.com"
12.     }
13.   },
14.   "paths": {
15.     "/users": {
16.       "get": {
17.         "summary": "获取用户列表",
18.         "x-rate-limit": "100/hour",
19.         "x-permission": "users:read",
20.         // 其他操作定义...
21.       }
22.     }
23.   }
24. }

复制代码

7. 组织大型API文档

对于大型API，考虑将文档拆分为多个文件，然后使用$ref引用它们：

2. {
3.   "openapi": "3.0.0",
4.   "info": {
5.     "title": "大型API",
6.     "version": "1.0.0"
7.   },
8.   "paths": {
9.     "/users": {
10.       "$ref": "paths/users.json"
11.     },
12.     "/products": {
13.       "$ref": "paths/products.json"
14.     },
15.     "/orders": {
16.       "$ref": "paths/orders.json"
17.     }
18.   },
19.   "components": {
20.     "schemas": {
21.       "User": {
22.         "$ref": "schemas/User.json"
23.       },
24.       "Product": {
25.         "$ref": "schemas/Product.json"
26.       },
27.       "Order": {
28.         "$ref": "schemas/Order.json"
29.       }
30.     },
31.     "securitySchemes": {
32.       "bearerAuth": {
33.         "$ref": "security/bearerAuth.json"
34.       }
35.     }
36.   }
37. }

复制代码

总结

通过本教程，我们深入探讨了Swagger JSON配置的各个方面，从基础结构到高级技巧。我们学习了如何：

1. 创建基本的Swagger JSON配置
2. 定义API路径和操作
3. 创建和引用数据模型
4. 实现安全配置
5. 处理常见API场景，如分页、文件上传和错误处理
6. 应用最佳实践来创建专业、可维护的API文档

Swagger JSON配置是创建专业API文档的关键工具。通过遵循本教程中的指南和示例，你可以创建出清晰、全面且易于使用的API文档，帮助开发者快速理解和使用你的API。

记住，好的API文档不仅仅是技术规范，它是开发者与你的服务交互的桥梁。投入时间和精力创建高质量的API文档，将大大提高你的API的采用率和开发者满意度。

现在，你已经掌握了Swagger JSON配置的核心概念和技巧，可以开始创建自己的专业API文档了！

版权声明

1、转载或引用本网站内容(实用Swagger JSON配置教程一步步教你打造专业API文档)须注明原网址及作者(威震华夏关云长)，并标明本网站网址(https://pixtech.org/)。

2、对于不当转载或引用本网站内容而引起的民事纷争、行政处理或其他损失，本网站不承担责任。

3、对不遵守本声明或其他违法、恶意使用本网站内容者，本网站保留追究其法律责任的权利。

本文地址: https://pixtech.org/thread-40211-1-1.html