第 4 章 如何编写 OpenAPI 文档以用作 3scale OpenAPI 规格
如果您只想读取代码,所有示例都位于 OAS Petstore 示例源代码 中。
3scale ActiveDocs 基于名为 Swagger (来自 Wordnik)的 RESTful Web 服务规格。本例基于 扩展的 OpenAPI 规范 Petstore 示例,从 OpenAPI 规范 2.0 规范文档中 获取所有 规范数据。
先决条件
- 开发人员门户上需要使用符合 REST API 的 OpenAPI 规范(OAS)规范。
OAS 不仅仅是一个规范。它还提供了一个完整的功能框架:
- 以多种语言(NodeJS、Scala 等)指定资源的服务器。
- 组 HTML/CSS/Javascripts 资产,用于提取规范文件并生成极具吸引力的 UI。
- OAS codegen 项目,允许从兼容 Swagger 的服务器中自动生成客户端库。支持使用多种现代语言创建客户端侧库。
4.1. 设置 3scale ActiveDocs 和 OAS
ActiveDocs 是 OAS 实例。使用 ActiveDocs 时,您不必运行自己的 OAS 服务器或处理交互式文档中的用户界面组件。交互式文档通过 3scale 开发人员门户提供和呈现。
3scale 2.8 引入了 OAS 3.0,在 ActiveDocs 中受到有限支持。这意味着,一些使用 ActiveDocs 的功能(如自动完成)尚未完全集成,因此 3scale 在创建新帐户时默认为 OAS 2.0。有关 OAS 3.0 和 ActiveDocs 的详情,请参考 第 2.1 节 “OpenAPI 规范 3.0 使用 3scale”。
先决条件
- 确保开发人员门户中使用的模板实施与管理门户中指定的相同 OAS 版本。
步骤
- 构建符合 OAS 的 API 规格。
- 将规格添加到您的管理门户。
结果
您的 API 互动文档现已正式发布。API 用户可以通过开发人员门户发送请求到您的 API。
如果您已经有与 OAS 兼容的 API 规格,您可以在 Developer Portal 中添加它。请参阅 ActiveDocs 配置的教程。
3scale 以多种方式扩展 OAS,以适应开发人员门户互动 API 文档所需的某些功能:
- 自动填充 API 密钥
- OAS 代理,允许调用非CORS 的 API