api响应泛型参数 swagger_OpenAPI规范和Swagger简介

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库解析开发人