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