4.3. 其他 OAS 规格信息

如果您希望您的文档类似 OAS Petstore 文档,您必须创建与 Swagger 兼容的规范,如关联的 Petstore swagger.json 文件。您可以使用此规格开箱即用测试您的 ActiveDocs。但请记住,这不是您的 API。

OAS 依赖于映射到 JSON 编码的散列的资源声明。使用 Petstore swagger.json 文件作为示例,并了解每个对象。

OAS 对象

这是 API 规格的根文档对象。它列出所有最高级别字段。

info 对象

info 对象提供有关 API 的元数据。此内容将显示在 ActiveDocs 页面中。

路径 对象

path 对象 包含到单个端点的相对路径。该路径附加到基本路径中,以构造完整的 URL。由于访问控制列表(ACL)约束,路径 可能为空。

不是对象的参数使用原语数据类型。在 Swagger 中,原始数据类型基于 JSON-Schema Draft 4 支持的类型。有一个额外的原语数据类型 文件,但 3scale 仅在 API 端点启用了 CORS 时才使用该文件。启用 CORS 后,上传不会通过 api-docs 网关,它会被拒绝。

目前 OAS 支持以下 dataType:

  • 带有可能的格式的整数:int32 和 int64。两种格式都是签名的。
  • 带有可能格式的数字:浮点数和双倍
  • 纯文本字符串
  • 带有可能的格式的字符串:字节、日期、日期、密码和二进制
  • 布尔值