大部分 Web 应用程序都支持 RESTful API，但不同于 SOAP API——REST API 依赖于 HTTP 方法，缺少与 Web 服务描述语言（Web Services Description Language，WSDL）类似的语言来定义使用者与提供者之间的请求和响应结构。由于没有充分的合同服务，许多 REST API 提供者使用 Microsoft Word 文档或维基页面来记录 API 用法。这些格式使协作和文档版本控制变得很困难，尤其对于有许多 API 或资源的应用程序，或者在 API 采用迭代式开发方式时。这些文档类型在集成到自动化测试应用程序中时变得更难。
开源 Swagger 框架帮助 API 使用者和开发人员纠正了这些问题。该框架为创建 JSON 或 YAML（JSON 的一个人性化的超集）格式的 RESTful API 文档提供了 OpenAPI 规范（以前称为 Swagger 规范）。Swagger 文档可由各种编程语言处理，可在软件开发周期中签入源代码控制系统中，以便进行版本管理。
但是 Swagger 本身也有不足之处。当我们使用该框架记录自己的 API 时，会发现我们的文档需求与 Swagger 的基本功能之间存在空白。我们将介绍我们在文档化过程中遇到的挑战，并展示如何通过以下方法解决它们：
实现 Swagger 扩展
简化 Swagger 的功能来聚合文档
创建一个输出 Swagger 文档为 HTML 页面的工具
我们开发的解决方案可通过下载获得（参见“”）。您可以修改我们的示例，以便使用 Swagger 为您自己的 RESTful API 创建文档，并（使用您在本文中学到的技术）创建您自己的 Swagger 定制化。
使用 Swagger一些 Swagger 编辑工具可帮助您轻松地创建 API 文档，确保它们遵守 OpenAPI 规范。举例而言，通过使用 ，您可以创建或导入 API 文档，并在一个交互式环境中浏览它。右侧的显示窗格显示了格式化的文档，反映了您在左侧窗格中的代码编辑器中执行的更改。代码编辑器指出了所有格式错误。您可以展开和折叠每个窗格。
以下是您导入 leads.yaml 定义后的 Swagger Editor UI 外观：
放在屏幕截图上的红色箭头表示基于 OpenAPI 规范的 leads.yaml 文件中的 post: 和 get: 定义，与预览文档中 POST 和 GET API 的文档之间的对应关系。
如果使用 Eclipse 作为 IDE，您可以使用 YEdit，它会检查并突出显示 YAML 语法，还会提供编辑和格式化功能。
扩展 Swagger现有的工具使编辑 Swagger API 文档变得很容易，但某些文档场景带来了一些挑战。以下这些是我们在使用 Swagger 记录自己的 API 文档时遇到的一些实际问题：
API 使用者需要获得特定于我们的 API 的信息，但 OpenAPI 规范不包含该信息的标准。
API 使用者需要请求和响应示例，但现有的编辑器无法包含它们。
我们需要提供一个容易阅读的富文档，其中包含可供 API 使用者使用的示例，最好是采用在线 HTML 文档形式。
为了解决这些问题，我们根据 OpenAPI 规范创建了自己的属性、工具和模板。
扩展属性您可以使用 x- 扩展属性来扩展 Swagger。以下是我们为自己的 API 专门定制的一些扩展，以及它们的用法示例：
以下属性用于 API 有效负载或响应字段：
x-sc-crud：记录一个 API 字段的有效创建、读取、更新和删除（CRUD）操作：
1
x-sc-crud: [ read, update, create ]
x-sc-required：指示此字段需要哪些 CRUD 操作：
1
x-sc-required: [ create ]
x-sc-fieldmap：记录与指定的 API 字段关联的数据库表和 UI 字段：
1 2 3
x-sc-fieldmap: table: TASKS_RELATED_TO uifieldname: Related to
x-sc-enum：记录 API 字段的有效值。可以不使用静态值列表，而指定一个返回当前的可能值集合的 API。
1 2
x-sc-enum: api: /leads/enum/alt_address_country
x-sc-comments：为 description 属性提供补充，，用于捕获给定 API 字段的额外的临时信息：
1 2
x-sc-comments: - readonly in UI, aka Domestic Buying Group or DB
下面的清单是 Lead 模块中的 lead_source API 字段的 YAML 定义中的 x-sc 属性的示例：
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37
lead_source: type: string maxLength: 100 externalDocs: description: Lead Source // Current (0100) // Approved // op - Opportunity url: https://w3.ibm.com/standards/information/tmt/output/Approved/ ibmww/op/bds/Opportunity_Management/Lead_Source.html # # lead_source value is returned when retrieving a lead, # and you can set its value when creating or updating a Lead. # x-sc-crud: [ read, update, create ] # # The lead_source is a required field when creating a Lead. # x-sc-required: [ create ] # # You can retrieve valid lead_source values from the # /leads/enum/lead_source API. # x-sc-enum: api: /leads/enum/lead_source AVL: dictionary_name: leads_lead_source_dom example: LinkedIn # # The value of lead_source is saved in the LEADS table. # In UI, you can find lead_source under the "Lead Source" label. # x-sc-fieldmap: table: LEADS uifieldname: Lead Source
以下属性扩展了 API 操作的描述：
以下是 /leads API 端点的 HTTP POST 方法的 YAML 资源中的 x-sc 属性示例：
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50
paths: /leads: parameters: - $ref: ‘MASTER#/parameters/OAuthToken‘ - $ref: ‘MASTER#/parameters/ContentType‘ post: summary: create lead tags: [ leads ] # # Use the x-sc-APIm-plans property to specify that this endpoint # is in APIm‘s salesconnect_leads_create plan. # x-sc-APIm-plans: - salesconnect_leads_create description: | <p>API to create a lead.</p> # # Use the x-sc-samples property to refer to samples of the usage # of the /leads API. # x-sc-samples: - $ref: ‘#/x-sc-samples/leads-post-create-lead‘ - $ref: ‘#/x-sc-samples/leads-post-create-lead-employeecnum‘ parameters: - name: lead_definition in: body description: definition of lead to be created schema: $ref: ‘#/definitions/LeadObject‘ responses: 200: $ref: ‘#/responses/LeadObjectResponse‘ 422: description: | <p>scenarios</p> <ul> <li>missing required field</li> <li>invalid values for optional fields</li> <li>et cetera</li> </ul>
包含示例
尽管 Swagger 是一个定义 RESTful API 的强大工具，但它未提供用于包含 HTTP 请求和响应示例，或者用于为开发人员添加已编写文档的途径。