我们看到 Swagger 是一款开源的 API 文档工具，它可以根据 API 代码自动生成文档和测试用例，并提供了一个可视化的界面方便查看和测试 API。Swagger 之的好处在于：
- 自动生成 API 文档：Swagger 可以根据 API 代码自动生成 API 文档，避免了手动编写 API 文档的繁琐和容易出错的过程。
- 提供可视化的 API 测试界面：Swagger 提供了一个可视化的测试界面，方便开发人员测试 API，减少了调试时间和工作量。
- 支持多种编程语言：Swagger 支持多种编程语言，可以用于不同的项目，提高了开发效率。
- 提供 API 规范：Swagger 提供了一套 API 规范，包括 API 请求和响应格式、错误码等，方便开发人员编写API，并提高了API 的可读性和可维护性。
- 可扩展性强：Swagger 支持扩展，可以根据不同的需求添加自定义的插件，满足各种不同的需求。
下面是是一个 OpenAPI 3.0 的例子，JSON 文件由一个大 JSON 组成，并包含了若干个 OpenAPI 文档对象。
{
"openapi": "3.0.0",
"info": {
"description": "A service for checking credit for an account.",
"version": "1.0.0",
"title": "Credit Decision",
"termsOfService": "http://swagger.io/terms/",
"contact": {
"email": "apiteam@swagger.io"
},
"license": {
"name": "Apache 2.0",
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
}
},
"servers": [
{
"url": "https://<YourHostName>"
}
],
"paths": {
"/account/lastCreditRating": {
"get": {
"summary": "Evaluates credit rating and decides what payment terms to offer.",
"description": "",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/accountId"
}
},
"application/xml": {
"schema": {
"$ref": "#/components/schemas/accountId"
}
}
},
"description": "Specifies input parameters to calculate payment term",
"required": true
},
"responses": {
"200": {
"description": "success",
"content": {
"application/xml": {
"schema": {
"$ref": "#/components/schemas/creditRating"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/creditRating"
}
}
}
},
"405": {
"description": "Invalid input"
}
}
}
}
},
"components": {
"schemas": {
"accountId": {
"type": "object",
"properties": {
"accountIdString": {
"type": "string"
}
},
"xml": {
"name": "accountId"
}
},
"creditRating": {
"type": "object",
"properties": {
"creditRatingString": {
"type": "string"
}
},
"xml": {
"name": "creditRating"
}
}
}
}
}
OpenAPI 文档对象
下表中完整介绍了 OpenAPI 文档中常用对象。
| 字段名 | 类型 | 描述 |
|---|---|---|
| openapi | string | 必选. 这个字符串必须是开放API规范版本号提到的符合语义化版本号规范的版本号。openapi字段应该被工具或者客户端用来解释 OpenAPI 文档。这个值和API info.version字符串没有关联。 |
| info | Info 对象 | 必选。此字段提供API相关的元数据。相关工具可能需要这个字段。 |
| servers | [Server 对象] | 这是一个Server对象的数组， 提供到服务器的连接信息。如果没有提供servers属性或者是一个空数组，那么默认为是url值为/的 Server 对象 。 |
| paths | Paths 对象 | 必选。对所提供的API有效的路径和操作。 |
| components | Components 对象 | 一个包含多种结构的元素。 |
| security | [Security Requirement 对象] | 声明API使用的安全机制。The list of values includes alternative security requirement objects that can be used. 认证一个请求时仅允许使用一种安全机制。单独的操作可以覆盖这里的定义。 |
| tags | [Tag 对象] | 提供更多元数据的一系列标签，标签的顺序可以被转换工具用来决定API的顺序。不是所有被Operation 对象用到的标签都必须被声明。没有被声明的标签可能被工具按自己的逻辑任意整理，每个标签名都应该是唯一的。 |
| externalDocs | External Documentation 对象 | 附加的文档。这个对象可能会被规范扩展扩展。 |
数据格式列表
下表是 OpenAPI 文档中支持的原始数据类型。
| 通用名 | type | format | 备注 |
|---|---|---|---|
| integer | integer | int32 | 32 位有符号 |
| long | integer | int64 | 64 位有符号 |
| float | number | float | |
| double | number | double | |
| string | string | ||
| byte | string | byte | base64 编码的支付 |
| binary | string | binary | 任意 8进制序列 |
| boolean | boolean | ||
| date | string | date | 定义于 full-date - RFC3339 |
| dateTime | string | date-time | 定义于 date-time - RFC3339 |
| password | string | password | 告知输入界面不应该明文显示输入信息。 |
扩展阅读《 OpenAPI 规范的中文版》
想要了解更多 Swagger 文档编写规则，推荐阅读 OpenAPI 规范中文版。
对于不少小伙伴，可能感觉需要通读标准还是有点工作量，我们推荐直接采用 Apifox 设计 API。Apifox 是一款设计、文档和测试 API 的一体化工具，使用 Apifox 设计 API 有以下好处：
- 提高开发效率：Apifox 提供了可视化的设计工具，可以快速设计出 API，减少手动编写代码的时间和工作量。
- 减少错误：使用 Apifox 可以减少因手动编写 API 文档和测试代码而产生的错误，从而提高 API 的质量和稳定性。
- 改善协作效率：Apifox 支持多人协作，可以协同开发、测试和文档编写，加快项目的进度。
- 提高可维护性：使用 Apifox 设计 API 可以提高 API 的可读性和可维护性，从而降低代码维护的成本。
- 方便管理：Apifox 提供了 API 的管理功能，可以方便地管理和维护 API，包括 API 的版本管理、权限管理、访问控制等。
其实在自动化测试，代码生成方面，gRPC 等多协议测试场景下有很多很便捷的功能，小伙伴们可以深入摸索下。
