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规范可能如下所示:
![9928bb49017bd8beca3468e6bbc63511.png](https://i-blog.csdnimg.cn/blog_migrate/464fc06664980d37659dd04839fd7e8e.jpeg)
此YAML代码来自Swagger Petstore演示。
这些对象的含义如下:
- / pets是端点路径。
- get 是HTTP方法。
- parameters 列出了端点的参数。
- responses 列出了请求的响应。
- 200 是HTTP状态代码。
- $ ref 是对实现的另一部分的引用,其中定义了响应(在组件中)。OpenAPI有很多这样的$ ref引用,以保持代码干净并促进重用。
验证规格
在编写OpenAPI规范文档时,可以在Swagger编辑器中编写代码,而无需在文本编辑器中工作。Swagger编辑器会动态验证您的内容,以确定您创建的规范文档是否有效。
![bdd9ad1d0ac8a0def1ac104ffa40fc3d.png](https://i-blog.csdnimg.cn/blog_migrate/2f3168d8b3f42f2b894c897694fbb46d.jpeg)
Swagger编辑器会动态验证您的规范内容,并在右侧显示您的显示
在Swagger编辑器中进行编码时,如果您出错了,则可以在继续之前快速修复它,而不必等到以后再运行构建并解决错误。
对于规范文档的格式,可以选择使用JSON或YAML。先前的代码示例在YAML中。YAML指的是“ YAML不是标记语言”,这意味着YAML没有任何标记标签(<>),这与XML等其他标记语言很常见。
YAML取决于间距和冒号来建立对象语法。这种对空间敏感的格式使代码更易于阅读,但有时正确设置间距也比较棘手。
通过代码注释自动生成OpenAPI文件
除了手动编写OpenAPI规范文档外,您还可以从编程代码中的注释自动生成它。如果您拥有大量的API,或者对于技术编写者而言,创建此文档不切实际,则这种以开发人员为中心的方法可能有意义。
Swagger提供了各种库,您可以将它们添加到编程代码中以生成规范文档。然后,这些Swagger库解析开发人