大家好，欢迎来到IT知识分享网。

OpenAPI是用于描述REST API的规范。您可以将OpenAPI规范视为DITA规范。使用DITA，有一些用于定义帮助组件的特定XML元素，以及这些元素的必需顺序和层次结构。不同的工具可以读取DITA并从该信息中建立文档网站。使用OpenAPI（而不是XML），您可以拥有一组JSON对象，它们具有定义其命名，顺序和内容的特定架构。此JSON文件（通常用YAML而不是JSON表示）描述了API的每个部分。通过以标准格式描述API，发布工具可以以编程方式解析有关API的信息，并以风格化的交互式显示方式显示每个组件。

目录

• 浏览OpenAPI规范
• 验证规格
• 通过代码注释自动生成OpenAPI文件
• 另一种方法：规范优先开发
• 技术规范作者的角色
• 使用Swagger UI呈现您的OpenAPI规范
• 活动：通过Petstore演示
• 探索Swagger UI其他阅读OpenAPI规范的工具
• 自定义Swagger UI
• OpenAPI和Swagger UI的缺点
• 一些安慰
• 资源和进一步阅读

浏览OpenAPI规范

为了更好地理解OpenAPI规范，让我们看一下一些规范摘录。我们将在即将到来的教程中更深入地研究每个元素。

‌此处的Github存储库中提供了OpenAPI规范的正式描述。一些OpenAPI元素是路径，参数，响应和安全性。这些元素都是一个JSON对象，其中包含一些属性和数组。

‌在OpenAPI规范中，端点是路径。如果您有一个称为“ pets”的端点，则此端点的OpenAPI规范可能如下所示：

此YAML代码来自Swagger Petstore演示。

这些对象的含义如下：

• / pets是端点路径。
• get 是HTTP方法。
• parameters 列出了端点的参数。
• responses 列出了请求的响应。
• 200 是HTTP状态代码。
• $ ref 是对实现的另一部分的引用，其中定义了响应（在组件中）。OpenAPI有很多这样的$ ref引用，以保持代码干净并促进重用。

验证规格

在编写OpenAPI规范文档时，可以在Swagger编辑器中编写代码，而无需在文本编辑器中工作。Swagger编辑器会动态验证您的内容，以确定您创建的规范文档是否有效。

Swagger编辑器会动态验证您的规范内容，并在右侧显示您的显示

‌在Swagger编辑器中进行编码时，如果您出错了，则可以在继续之前快速修复它，而不必等到以后再运行构建并解决错误。

对于规范文档的格式，可以选择使用JSON或YAML。先前的代码示例在YAML中。YAML指的是“ YAML不是标记语言”，这意味着YAML没有任何标记标签（<>），这与XML等其他标记语言很常见。

YAML取决于间距和冒号来建立对象语法。这种对空间敏感的格式使代码更易于阅读，但有时正确设置间距也比较棘手。

通过代码注释自动生成OpenAPI文件

除了手动编写OpenAPI规范文档外，您还可以从编程代码中的注释自动生成它。如果您拥有大量的API，或者对于技术编写者而言，创建此文档不切实际，则这种以开发人员为中心的方法可能有意义。

Swagger提供了各种库，您可以将它们添加到编程代码中以生成规范文档。然后，这些Swagger库解析开发人员添加的注释并生成OpenAPI规范文档。这些库被视为Swagger Codegen项目的一部分。注释方法因编程语言而异。例如，这是有关使用Swagger for Scalatra注释代码的教程。有关Codegen的更多信息，请参阅API Evangelist的Swagger自动API代码生成工具比较。有关其他工具和库，请参见Swagger服务和工具和开源集成。

尽管这种方法可以“自动”生成规范，但是仍然有人必须知道要添加哪些注释以及如何添加注释（此过程与Javadoc的注释和注释不太相似）。然后，有人必须为每个注释的值（描述端点，参数等）编写内容。简而言之，这个过程并非没有花力，自动化的部分是让Codegen库生成模型定义和符合OpenAPI架构的有效规范文档。

尽管如此，许多开发人员仍对这种方法感到兴奋，因为它提供了一种从代码注释生成文档的方法，这是开发人员多年来与其他编程语言（例如Java（使用Javadoc）或C ++（使用Doxygen））一起所做的事情。他们通常认为从代码生成文档可以减少文档漂移。如果文档与代码紧密结合，则文档可能会保持最新状态。

如果走这条路，请确保可以访问源代码以对注释进行编辑。否则，您的开发人员将编写您的文档（虽然很好，但通常会导致结果不佳）。

另一种方法：规范优先开发

尽管您可以从代码注释中生成规范文档，但许多人认为自动生成并不是最佳方法。Michael Stowe在《不受干扰的REST：完美API设计指南》中，建议团队手动实施规范，然后将规范文档视为开发人员在进行实际编码时使用的合同。这种方法通常称为“规范优先开发”。

规范优先开发是关于如何更有效地开发API的理念。如果您遵循规范优先的原则，那么您将首先编写规范并将其用

换句话说，开发人员请查阅规范文档，以了解应调用的参数名称，响应的名称，等等。确立了此“合同”或“蓝图”之后，Stowe说您可以将注释放入代码中（如果需要），从而以更自动化的方式生成规范文档。但是在没有规格之前不要编码。

很多时候，开发团队会迅速跳转到对API端点，参数和响应进行编码的过程，而无需进行大量的用户测试或研究API是否符合用户的需求。由于版本控制API非常困难（您必须支持每个新版本都必须具有与先前版本完全向后兼容的功能），因此您要避免敏捷爱好者通常庆祝的“快速失败”方法。没有什么比发布新版本的API（使先前版本中使用的端点或参数无效）更糟糕的了。API中的恒定版本控制可能会成为文档的噩梦。

在我与SwaggerHub（团队合作使用Swagger API规范的协作平台）的公司Smartbear进行的交谈中，他们说，现在团队手动编写规范而不是将源注释嵌入编程代码中以自动生成，现在更为普遍。规格。规范优先的方法有助于将文档工作分配给比工程师更多的团队成员。在编码之前定义规范还有助于团队开发出更好的API。

甚至在对API进行编码之前，您的规范就可以通过在规范中添加响应定义来生成模拟响应。模拟服务器生成的响应看起来像是来自真实服务器的响应，但这只是代码中的预定义响应，对于用户而言似乎是动态的。

技术规范作者的角色

在我的大多数项目中，开发人员对Swagger或OpenAPI并不熟悉，因此我通常手动创建OpenAPI规范文档。此外，我通常无法访问编程源代码，并且我们的开发人员只会说英语作为第二或第三语言。他们不希望从事文档业务。

您很可能会发现您公司的工程师对Swagger或OpenAPI并不熟悉，但是有兴趣将其用作API文档的一种方法（基于架构的方法符合工程学的思维方式）。因此，您可能需要带头指导工程师，以获取必要的信息，方法和其他细节，以符合创建规范的最佳实践。

在这方面，技术作者在与API团队合作制定规范中可以发挥关键作用。如果您遵循规范优先的开发理念，那么这个领导角色可以帮助您在对API进行编码和锁定之前对其进行调整。这意味着您可能有机会影响端点的名称，一致性和模式，简单性以及API设计中通常要考虑的其他因素。

使用Swagger UI呈现您的OpenAPI规范

在拥有描述您的API的有效OpenAPI规范文档之后，您可以将该规范提供给其他工具以进行解析，并生成类似于Petstore演示的交互式文档。

‌可能最常用的解析OpenAPI规范的工具是Swagger UI。（请记住，“ Swagger”是指API工具，而“ OpenAPI”是指与供应商无关的，与工具无关的规范。）下载Swagger UI后，很容易使用自己的规范文件对其进行配置。我将在接下来的部分中提供Swagger UI教程。

‌Swagger UI代码生成如下所示的显示：

Swagger Petstore演示展示了Swagger UI如何呈现OpenAPI规范

您还可以使用简单的天气API（作为课程示例）来查看Swagger UI示例集成。

一些设计师批评Swagger UI的可扩展/可折叠输出过时。同时，开发人员发现一页模型很有吸引力，并且喜欢放大或放大细节的功能。通过在一个视图中整合所有端点在同一页面上，用户可以一目了然地使用整个API。该显示使用户可以大致了解整体情况，这有助于降低复杂性并使其入门。在许多方面，Swagger UI显示是API的快速参考指南。

活动：通过Petstore演示探索Swagger UI

让我们通过Petstore演示获得Swagger UI的实际操作经验。Petstore演示提供了一个很好的示例，说明如何以可视方式呈现OpenAPI规范。

1. 转到Swagger宠物商店演示。 与大多数基于Swagger的输出一样，Swagger UI提供了“试用”按钮。要使其正常工作，您必须首先通过单击“授权”并在“授权”模式中输入您的API密钥来授权Swagger。但是，Petstore授权模式仅用于演示目的。没有真正的代码授权这些请求，因此您可以关闭“授权”模式或完全跳过它。

Swagger UI中的授权模式

2. 展开POST / pet端点。

POST / pet端点并在Swagger UI中尝试一下按钮

3. 点击试用。

单击“试用”后，“请求正文”字段中的示例值将变为可编辑的。

4. 在示例值中，将第一个id值更改为唯一的（并且不太可能重复）整数（例如24329）。将名称doggie更改为您可以记住的宠物名称（例如Bentley）。

5. 单击执行。

执行样本Petstore请求

Swagger UI提交请求并显示已提交的curl。例如，这是发送的curl Swagger UI：

curl -X POST "https://petstore.swagger.io/v2/pet" -H "accept: application/xml" -H "Content-Type: application/json" -d "{ \"id\": 1000, \"category\": { \"id\": 0, \"name\": \"string\" }, \"name\": \"Bentley\", \"photoUrls\": [ \"string\" ], \"tags\": [ { \"id\": 0, \"name\": \"string\" } ], \"status\": \"available\"}"

请注意，使用-d（数据）参数，可以将请求正文参数转义并直接添加到curl命令中，而不是从文件中加载（如与REST相关的Common curl命令中所述）。

Swagger UI中的“响应”部分显示了来自服务器的响应。默认情况下，响应返回JSON：

{ "id": 1000, "category": { "id": 0, "name": "string" }, "name": "Bentley", "photoUrls": [ "string" ], "tags": [ { "id": 0, "name": "string" } ], "status": "available" }

6. Petstore是一个正常运行的API，您实际上已经创建了一个宠物。为了娱乐起见，展开GET / pet / {petId}端点，单击“试用”，输入在上一个操作中使用的宠物ID，然后执行请求。您应该会看到宠物的名字回来了。

其他阅读OpenAPI规范的工具

除了Swagger UI之外，还有其他工具可以解析您的OpenAPI规范文档。其中一些工具包括Restlet Studio，Apiary，Apigee，Lucybot，Gelato，Readme.io，swagger2postman，swagger-ui响应主题，Postman Run Buttons等。

一些Web设计人员已经将OpenAPI与静态网站生成器（例如Jekyll）集成在一起（请参见Carte和Readme）。您也可以将Swagger UI嵌入到网页中。定期推出更多工具来解析和显示OpenAPI规范文档中的内容。

实际上，一旦有了有效的OpenAPI规范，就可以使用称为API Transformer的工具将其转换为其他API规范格式，例如RAML或API Blueprint。这些附加格式使您可以扩展工具范围。

自定义Swagger UI

您可能会担心Swagger UI输出看起来很相似。通常，在OpenAPI项目中，我会稍微自定义Swagger UI的颜色，添加自定义徽标和其他一些自定义样式。在一个项目中，我集成了Bootstrap，因此我可以使用模式来使用户生成其授权代码。您甚至可以在description元素中添加折叠和展开功能，以向用户提供更多信息。

除了这些简单的修改之外，还需要一些Web开发人员的才能来显着更改Swagger UI显示。可以，但是您需要网络开发技能。

OpenAPI和Swagger UI的缺点

尽管Swagger具有交互式功能可以吸引用户的“让我尝试”的愿望，但是Swagger和OpenAPI仍有一些缺点：

• 仅供参考的文档：首先，OpenAPI规范和Swagger UI的输出仅涵盖参考文档。OpenAPI提供了每个端点的基础，包括描述，参数，示例请求和响应。它没有提供入门指南的空间，有关如何获取API密钥，如何运行示例应用程序的信息，与速率限制有关的信息，也没有为开发人员提供概念性主题的其他数百个详细信息。因此，即使您拥有此炫酷的交互式工具供用户探索和了解您的API，您仍然必须提供用户指南。举例来说，为基于库的API提供Javadoc或Doxygen输出不会教用户如何实际使用您的API。您仍然必须描述使用类或方法的方案，解释如何设置代码，如何处理响应，如何对问题进行故障排除等。简而言之，您仍然必须编写实际的帮助指南和教程。
• 信息的冗余/重复：混合使用OpenAPI，您可能在两个地方描述端点和参数（Swagger UI参考输出和用户指南），并且必须使两者保持同步，彼此嵌入，或者在两者之间建立链接。我将在与其他文档集成的Swagger UI中探索集成策略。
• API工作流程的复杂性：API的复杂性还会对Swagger造成限制。Peter Gruenbaum发布了一些有关在Udemy上编写API文档的教程，他说Swagger等自动化工具在API简单时效果最佳。如果您的端点之间具有复杂的相互依赖性，并且需要特殊的设置工作流程或其他不直观的处理方法，那么Swagger的“试用”界面的直截了当的性质可能会使用户挠头。例如，如果您必须先配置一个API服务，然后一个端点返回任何东西，然后使用一个端点来获取某个对象，然后将该对象传递到另一个端点的参数中，等等，等等。如果不遵循详细的教程，那么Swagger UI输出对用户来说就没有多大意义。
• 针对真实数据执行请求：某些用户可能没有意识到点击“试用”会根据他们使用的API密钥针对自己的帐户进行实际调用。稍后，当用户询问如何删除所有测试数据或为什么现在将其实际数据弄乱时，将邀请使用邀请函（如Swagger）和探索性沙箱与真实数据混在一起会造成一些麻烦。对于这些情况，最好为用户设置一个沙箱或测试帐户。但这说起来容易做起来难。您可能会发现您的公司没有提供用于测试API的沙箱。所有API调用均针对真实数据执行。
• CORS限制：在执行API调用时，您可能会遇到CORS（跨域资源共享）限制。并非所有的API都会接受从网页执行的请求。如果调用没有执行，请打开JavaScript控制台，然后检查CORS是否阻止了该请求。如果是这样，您需要请开发人员进行调整，以适应网页上JavaScript发出的请求。有关更多详细信息，请参见CORS支持。
• 广泛的请求主体参数有问题：最后，我发现带有冗长的请求主体参数的端点往往有问题。我必须记录的一个API包含带有几百行长的请求主体参数的请求（该请求主体用于配置API服务器）。有了这种请求正文参数，Swagger UI的显示就无法使用。该团队恢复了使用更为原始的方法（例如表格和Excel电子表格）来列出所有参数及其说明。

一些安慰

尽管有OpenAPI规范的缺点，但我仍然强烈建议您使用它来描述您的API。OpenAPI迅速成为越来越多的工具（从Postman Run按钮到几乎每个API平台）快速摄取有关您的API信息的方法，并使其通过健壮且具有指导性的工具可被发现和交互。通过您的OpenAPI规范，您可以将API移植到许多平台和系统上，并自动设置单元测试和原型制作。

Swagger UI绝对为API提供了很好的视觉效果。您可以轻松查看所有端点及其参数（如快速参考指南）。基于此框架，您可以帮助用户掌握API的基础知识。

此外，我发现学习OpenAPI规范并使用这些对象和属性描述我的API有助于了解我自己的API词汇。例如，我意识到参数有四种主要类型：“路径”参数，“标头”参数，“查询”参数和“请求正文”参数。我了解到，使用REST的参数数据类型是“布尔”，“数字”，“整数”或“字符串”。我了解到，响应提供了包含“字符串”或“数组”的“对象”。

简而言之，实施规范使我对API术语有了一定的了解，进而帮助我以可靠的方式描述了API的各个组成部分。

OpenAPI可能不是适用于每个API的正确方法，但是如果您的API具有相当简单的参数，并且端点之间没有很多相互依赖关系，并且在探索API而不会使用户的数据有问题的情况下可行，则OpenAPI和Swagger UI可以作为强大的补充您的文档。您可以使用户能够自己尝试请求和响应。

有了这个交互式元素，您的文档将不仅仅是信息。通过OpenAPI和Swagger UI，您可以为用户创建一个空间，供其阅读文档并同时尝试使用API​​。这种结合倾向于为用户提供强大的学习体验。

资源和进一步阅读

有关OpenAPI和Swagger的更多信息，请参见以下资源：

• API Transformer
• APIMATIC
• Carte
• Swagger editor
• Swagger Hub
• Swagger Petstore demo
• Swagger Tools
• Swagger UI tutorial
• OpenAPI specification tutorial
• Swagger/OpenAPI specification
• Swagger2postman
• Swagger-ui Responsive theme
• Swagger-ui
• Undisturbed REST: A Guide to Designing the Perfect API, by Michael Stowe