在 Developer Portal 中提供 API

Red Hat 3scale API Management 2.11

正确配置的开发人员门户为 API 管理提供了许多功能。

摘要

本指南记录了在红帽 3scale API 管理 2.11 上开发人员门户的使用。

前言

定义 API 的 OpenAPI 文档是开发人员门户的基础。

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。我们从这四个术语开始:master、slave、黑名单和白名单。由于此项工作十分艰巨,这些更改将在即将推出的几个发行版本中逐步实施。详情请查看我们的 CTO Chris Wright 信息

部分 I. OpenAPI 规格

第 1 章 OpenAPI 规范简介

在红帽 3scale API 管理中,OpenAPI 规范(OAS)可帮助您优化管理 OpenAPI 文档。OpenAPI 规范(OAS)为您提供了更新现有服务或创建新服务的工具。

以下是 3scale 中 OAS 的特别考虑事项:

先决条件

  • 定义您的 API 的 OpenAPI 文档。
  • 3scale 2.11 实例租户的凭据(令牌provider_key)。

使用 OAS 时,3scale 中提供了以下功能:

注意

导入 OpenAPI 文档时,您可以创建或更新 ActiveDocs。请参阅 如何编写 OpenAPI 文档以用作 3scale 规范

  • 可以将 3scale 服务 system_name 作为可选参数传递,默认为 OAS 中的 info.title 字段。
  • 针对 OpenAPI 规范中定义的每个操作创建方法。

    • operation.operationId 字段中获取 方法 名称。
  • 在导入新的 API 定义前,所有现有 的映射规则 都会被删除。

    • 如果方法存在,则不会删除它们,然后再运行 命令。
  • 为 OpenAPI 规范中定义的每个操作创建规则。
  • 以下频道之一提供 OpenAPI 定义资源:

    • 可用路径 中的文件名
    • URL 格式 - toolbox 将尝试从给定地址下载。
    • stdin 标准输入流读取.

1.1. 3scale 中导入 OpenAPI 文档的命令行选项

3scale 命令行界面(CLI)提供多个选项,用于导入 OpenAPI 文档,它们定义了您要在 3scale 中管理的 API。以下是 openapi 选项的帮助信息:

NAME
    openapi - Import API definition in OpenAPI specification

USAGE
    3scale import openapi [opts] -d <dst> <spec>

DESCRIPTION
    Using an API definition format like OpenAPI, import to your 3scale API

OPTIONS
       -d --destination=<value>                   3scale target instance.
                                                  Format: "http[s]://<authentication>@3scale_domain"

 -t --target_system_name=<value>            Target system name

OPTIONS FOR IMPORT
    -c --config-file=<value>                      3scale toolbox
                                                  configuration file
                                                  (default:
                                                  $HOME/.3scalerc.yaml)
    -h --help                                     show help for this command
    -k --insecure                                 Proceed and operate even
                                                  for server connections
                                                  otherwise considered
                                                  insecure
    -v --version                                  Prints the version of this
                                                  command

1.2. 导入 API 规格的不同源

作为 3scale 管理员,您可以使用不同的源来导入 API 规格。下表中概述了它们,其中显示了从文件名路径、URL 和 stdin 检测 OpenAPI 定义的使用选项。

表 1.1. 检测 OpenAPI 定义

描述格式命令行使用

从文件名路径检测 OpenAPI 定义.格式会自动从文件名扩展名检测到。

JSONyaml

$ 3scale import openapi -d <destination> /path/to/your/spec/file.[json|yaml|yml]

从 URL 检测 OpenAPI 定义.格式会自动从 URL 的路径扩展检测到。

JSONyaml

$ 3scale import openapi -d <destination> http[s]://domain/resource/path.[json|yaml|yml]

stdin 检测 OpenAPI 定义.OpenAPI 资源的命令行参数为 -。格式通过解析器在内部自动检测。

JSONyaml

$ tool_to_read_openapi_from_source | 3scale import openapi -d <destination> -

第 2 章 如何配置 OpenAPI 规格

要使 OpenAPI 规范与 3scale 协同工作,需要为要使用的版本正确配置。

先决条件

  • 定义您的 API 的 OpenAPI 文档。
  • 3scale 2.11 实例租户的凭据(令牌provider_key)。

2.1. OpenAPI 规范 3.0 使用 3scale

3scale 提供对使用 OAS 3.0 的以下支持:

  • Developer Portal 中更新了 swagger-ui 以支持 OAS 3.0
  • swagger-ui 现在作为 webpack 资产(node_modules)包含在内。以前,它是从 Content Delivery Network(CDN)中添加的。
  • 在管理门户中,任何新的 OAS 3.0 文档都会通过使用 swagger-ui 提供的功能来自动识别和处理。请注意,此功能需要在 Developer Portal 中进行配置。

您可以添加 OAS 3.0 规格到 ActiveDocs 中,并在 Developer Portal 中显示它们,考虑以下几点:

  • 您必须手动升级模板。
  • ActiveDoc 没有额外的功能,如尝试请求时使用凭证注入和使用服务名称等真实数据进行自动完成。

2.1.1. 使用 OAS 3.0 配置开发人员门户

此片段包括新版本的 swagger-ui,并呈现第一个可用的 ActiveDoc。请注意,它还将呈现 OAS 2.0,但不提供任何常见的 ActiveDocs 功能。

对 OAS 3.0 规格的支持需要在默认文档页面中提供以下内容:

{% content_for javascripts %}
 {{ 'active_docs.js' | javascript_include_tag }}
{% endcontent_for %}

{% assign spec = provider.api_specs.first %}

<h1>Documentation</h1>

<div class="swagger-section">
 <div id="message-bar" class="swagger-ui-wrap"></div>
 <div id="swagger-ui-container" class="swagger-ui-wrap"></div>
</div>

<script type="text/javascript">
 (function () {
   var url = "{{spec.url}}";
   var serviceEndpoint = "{{spec.api_product_production_public_base_url}}"
   SwaggerUI({ url: url, dom_id: "#swagger-ui-container" }, serviceEndpoint);
 }());
</script>

使用 OAS 3.0 更新 Developer Portal

如果您已在 3scale 2.8 中配置了 OAS 3.0,并希望继续使用 OAS 3.0,则需要更新模板。

这是要配置的模板:

{% content_for javascripts %}
    {{ 'active_docs.js' | javascript_include_tag }}
{% endcontent_for %}

<h1>Documentation</h1>

<div class="swagger-section">
  <div id="message-bar" class="swagger-ui-wrap">&nbsp;</div>
  <div id="swagger-ui-container" class="swagger-ui-wrap"></div>
</div>

<script type="text/javascript">
  (function () {
    var url = "{{provider.api_specs.first.url}}";

    SwaggerUI({ url: url, dom_id: "#swagger-ui-container" });
  }());
</script>

要更新模板,将默认文档页面替换为 第 2.1.1 节 “使用 OAS 3.0 配置开发人员门户” 中包含的代码片段。

2.2. OpenAPI 规格 2.0 使用 3scale

您可以添加 OAS 2.0 规格到 ActiveDocs 中,并在 Developer Portal 中显示它们,考虑以下几点:

  • 您必须手动升级模板。
  • ActiveDoc 没有额外的功能,如尝试请求时使用凭证注入和自动完成功能,如服务名称等实际数据。

对 OAS 2.0 规格的支持需要在默认文档页面中提供以下内容:

<h1>Documentation</h1>
{% cdn_asset /swagger-ui/2.2.10/swagger-ui.js %}
{% cdn_asset /swagger-ui/2.2.10/swagger-ui.css %}

{% include 'shared/swagger_ui' %}

<script type="text/javascript">
  $(function () {
    window.swaggerUi.options['url'] = "{{provider.api_specs.first.url}}";
    window.swaggerUi.load();
  });
</script>

2.3. 将 Swagger 用户界面 2.1.3 升级到 2.2.10

如果您使用包含 Swagger UI 2.1.3 的 3scale 版本,您可以升级到 Swagger UI 2.2.10。

之前的 3scale 开发人员门户网站中 Swagger UI 2.1.3 实施依赖于单个 {% active_docs 版本:在 Documentation 页面中,"2.0" %} 精简标签。随着在 3scale 中引入了对 Swagger 2.2.10 的支持,实施方法会更改为多个 cdn_asset 并包括适当的 标签。

注意

对于 Swagger UI 2.1.3 及更早版本,3scale 继续使用传统的 active_docs Mobile tag 方法调用 UI。

先决条件

  • 具有管理员访问权限的 3scale 实例。
  • 包含 Swagger UI 2.1.3 的 3scale 实例。

步骤

  1. 登录您的 3scale 管理门户。
  2. 导航到 Developer PortalDocumentation 页面,或您要更新 Swagger UI 的页面
  3. 在代码窗格的 Draft 选项卡中,替换 {% active_docs 版本:"2.0" %} 使用 cdn_asset Tag 以及新的 part shared/swagger_ui 标记:

    {% cdn_asset /swagger-ui/2.2.10/swagger-ui.js %}
    {% cdn_asset /swagger-ui/2.2.10/swagger-ui.css %}
    
    {% include 'shared/swagger_ui' %}
  4. 可选:默认情况下,Swagger UI 加载 API > ActiveDocs 中发布的 ActiveDocs 规格。通过在 window. swaggerUi. load()前面添加以下 window.swaggerUi.options 来加载不同的规格,其中 <SPEC_SYSTEM_NAME> 是您要加载的规格的系统名称:

    window.swaggerUi.options['url'] = "{{provider.api_specs.<SPEC_SYSTEM_NAME>.url}}";

部分 II. Developer Portal 中的 API 文档

第 3 章 将 ActiveDocs 添加到 3scale

3scale 提供了一个框架来为您的 API 创建交互式文档。

借助 OpenAPI 规范(OAS),您拥有 API 的功能文档,可帮助您的开发人员探索、测试和集成您的 API。

3.1. 在 3scale 中设置 ActiveDocs

您可以在 3scale 用户界面中将 ActiveDocs 添加到 API 中,以获取为您的 API 创建交互式文档的框架。

先决条件

  • 定义您的 API 的 OpenAPI 文档。
  • 3scale 2.11 实例租户的凭据(令牌provider_key)。

步骤

  1. 导航到管理门户中的 [your_API_name] → ActiveDocs。3scale 显示您的 API 服务规格列表。这最初为空。

    您可以根据需要添加更多服务规格。通常,每个服务规格都对应于您的一个 API。例如,3scale 具有每个 3scale API 的规格,如服务管理、帐户管理、分析分析和计费。

  2. 点击 Create a new spec

    添加新服务规格时,请执行以下操作:

    • Name
    • 系统名称.这需要引用 Developer Portal 中的服务规格。
    • 选择是否希望发布该规范。如果没有发布,则 Developer Portal 中将不提供新的规范。

      注意

      如果您创建但不发布新规范,则会在稍后进行选择时供您发布。

    • 添加仅供您使用的描述。
    • 添加 API JSON 规格。

      根据 OpenAPI 规范(OAS) 提出的规范生成 API 规格。在本教程中,我们假设您已具有与 API 的有效 OAS 兼容规格。

使用第一个 ActiveDoc

添加第一个 ActiveDoc 后,您可以在 [your_API_name] → ActiveDocs 中 看到它。您可以根据需要编辑、删除或将其从公共切换到私有。您可以从 API 分离,或将其附加到任何其他 API。您可以查看所有 ActiveDocs,无论它们是否附加到 Audience → Developer Portal → ActiveDocs 中的 API。

您可以通过单击您给定的服务规格的名称来预览 ActiveDocs 的样子,例如 Pet Store。即使规范尚未发布,您也可以执行此操作。

这是 ActiveDoc 类似的内容:

ActiveDocs 新规格视图

第 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 版本。

步骤

  1. 构建符合 OAS 的 API 规格。
  2. 将规格添加到您的管理门户。

结果

您的 API 互动文档现已正式发布。API 用户可以通过开发人员门户发送请求到您的 API。

如果您已经有与 OAS 兼容的 API 规格,您可以在 Developer Portal 中添加它。请参阅 ActiveDocs 配置的教程

3scale 以多种方式扩展 OAS,以适应开发人员门户互动 API 文档所需的某些功能:

  • 自动填充 API 密钥
  • OAS 代理,允许调用非CORS 的 API

4.2. OpenAPI 文档示例:Petstore API

要从原始源读取规格,请参阅 OpenAPI 规范

在 OAS 站点上,有多个定义 API 的 OpenAPI 文档示例。如果您希望按照示例学习,您可以按照 OAS API 团队的 Petstore API 示例进行操作。

Petstore API 是一个极其简单的 API。它是一种学习工具,而不是用于生产的工具。

Petstore API 方法

Petstore API 由 4 个方法组成:

  • GET /api/pets - 返回系统中的所有 pets
  • POST /api/pets - 在存储中创建新宠物
  • GET /api/pets/{id} - 根据单个 ID 返回 pet
  • DELETE /api/pets/{id} - 根据 ID 删除一个 pet

Petstore API 与 3scale 集成,因此您必须添加额外的参数来进行身份验证。例如,对于用户密钥身份验证方法,API 使用者必须将 user key 参数放在每个请求的标头中。有关其它验证方法的详情,请参考 身份验证模式

用户密钥参数

user_key: {user_key}

user_key 将由 API 用户在其请求中发送到您的 API。API 用户将使用 3scale 管理员的开发人员门户获取这些密钥。在收到密钥时,3scale 管理员必须使用 Service Management API 对 3scale 执行授权检查。

更多关于 OpenAPI 规范的信息

对于您的 API 用户,在 cURL 调用中表示的 API 文档应如下所示:

curl -X GET "http://example.com/api/pets?tags=TAGS&limit=LIMIT" -H "user_key: {user_key}"
curl -X POST "http://example.com/api/pets" -H "user_key: {user_key}" -d "{ "name": "NAME", "tag": "TAG", "id": ID }"
curl -X GET "http://example.com/api/pets/{id}" -H "user_key: {user_key}"
curl -X DELETE "http://example.com/api/pets/{id}" -H "user_key: {user_key}"

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。两种格式都是签名的。
  • 带有可能格式的数字:浮点数和双倍
  • 纯文本字符串
  • 带有可能的格式的字符串:字节、日期、日期、密码和二进制
  • 布尔值

4.4. OAS 设计和编辑工具

以下工具可用于设计和编辑定义您的 API 的 OpenAPI 规格:

  • 开源 Apicurio Studio 允许您在基于 Web 的应用中设计和编辑基于 OpenAPI 的 API。Apicurio Studio 提供设计视图,因此您无需详细了解 OpenAPI 规范。源视图可让专家用户直接在 YAML 或 JSON 中编辑。如需了解更多详细信息,请参阅 Apicurio Studio 入门

    红帽还提供名为 API Designer 的轻量级 Apicurio Studio,包含在 OpenShift 上的 Fuse Online 中。如需了解更多详细信息,请参阅 开发和部署 API 提供程序集成。

  • 如果您非常熟悉 JSON 表示法,可以使用 JSON Editor Online。它为 JSON 紧凑提供了很好的格式,并提供 JSON 对象浏览器。
  • Swagger Editor 允许您创建和编辑浏览器中以 YAML 语言编写的 OAS API 规格,并实时预览。您还可以生成有效的 JSON 规格,稍后您可以在 3scale 管理门户中上传该规范。您可以使用功能有限的 live 演示 版本,或部署自己的 OAS Editor。

4.5. ActiveDocs 自动填充 API 密钥

在 3scale ActiveDocs 中自动填充 API 密钥是 OAS 的有用扩展。您可以根据 API 身份验证模式,使用以下值定义 x-data-threescale-name 字段:

  • user_keys :返回仅使用 API 密钥身份验证的服务应用的用户密钥。
  • app_ids :返回使用 App ID/App Key 的服务应用的 ID。OAuth 和 OpenID Connect 也支持向后兼容。
  • app_keys :返回使用 App ID/App Key 的服务应用程序的密钥。OAuth 和 OpenID Connect 也支持向后兼容。

API 密钥验证示例

以下示例显示了只将 "x-data-threescale-name": "user_keys" 用于 API 密钥验证:

"parameters": [
  {
    "name": "user_key",
    "description": "Your access API Key",
    "type": "string",
    "in": "query",
    "x-data-threescale-name": "user_keys",
    "required": true
  },
]
应用程序 ID/App 密钥验证示例

x-data-threescale-name 字段是忽略 ActiveDocs 域之外的 OAS 扩展。

对于 App ID/App Key 身份验证模式,请为代表应用程序 ID 的参数指定 "x-data-threescale-name": "app_ids ",为代表应用程序密钥的参数指定 "x-data-threescale-name": "app_keys"。

声明了参数后,ActiveDocs 会自动提示 ActiveDocs 用户登录到 Developer Portal 来获取其密钥,如以下屏幕截图所示:

未登录时自动填充

如果用户已经登录,ActiveDocs 会显示与他们相关的最新五个密钥,以便他们可以立即测试,而无需复制并粘贴其密钥。

登录时自动填充

第 5 章 ActiveDocs 和 OAuth

ActiveDocs 允许您从一个位置测试和调用支持 OAuth 的 API。

先决条件

5.1. 3scale 规范中的客户端凭证和资源所有者流示例

第一个示例是在 3scale 规格中使用 OAuth 2.0 客户端凭证流的 API。此 API 接受任何路径,并返回有关请求的信息(路径、请求参数、标头等)。Echo API 只能通过使用有效的访问令牌来访问。API 用户只能在交换其凭据(client_id 和 client_secret )来获取访问令牌后将其调用。

要使用户能够从 ActiveDocs 调用 API,他们必须请求访问令牌。由于这仅仅是对 OAuth 授权服务器的调用,因此您可以为 OAuth 令牌端点创建 ActiveDocs 规格。这允许从 ActiveDocs 中调用此端点。在本例中,对于客户端凭证流,Swagger JSON 规格类似如下:

{
  "swagger": "2.0",
  "info": {
    "version": "v1",
    "title": "OAuth for Echo API",
    "description": "OAuth2.0 Client Credentails Flow for authentication of our Echo API.",
    "contact": {
      "name": "API Support",
      "url": "http://www.swagger.io/support",
      "email": "support@swagger.io"
    }
  },
  "host": "red-hat-sso-instance.example.com",
  "basePath": "/auth/realms/realm-example/protocol/openid-connect",
  "schemes": [
    "http"
  ],
  "paths": {
    "/token": {
      "post": {
        "description": "This operation returns the access token for the API. You must call this before calling any other endpoints.",
        "operationId": "oauth",
        "parameters": [
          {
            "name": "client_id",
            "description": "Your client id",
            "type": "string",
            "in": "query",
            "required": true
          },
          {
            "name": "client_secret",
            "description": "Your client secret",
            "type": "string",
            "in": "query",
            "required": true
          },
          {
            "name": "grant_type",
            "description": "OAuth2 Grant Type",
            "type": "string",
            "default": "client_credentials",
            "required": true,
            "in": "query",
            "enum": [
                "client_credentials",
                "authorization_code",
                "refresh_token",
                "password"
            ]
          }
        ]
      }
    }
  }
}

对于资源所有者 OAuth 流,为用户名和密码以及发布访问令牌所需的其他参数添加参数。对于此客户端凭据流,您将发送 client_idclient_secret,这些值可以从已签名用户以及 grant_type 的 3scale 值填充。

然后,在 Echo API 的 ActiveDocs 规格中添加 access_token 参数,而不是 client_idclient_secret

{
  "swagger": "2.0",
  "info": {
    "version": "v1",
    "title": "Echo API",
    "description": "A simple API that accepts any path and returns information about the request",
    "contact": {
      "name": "API Support",
      "url": "http://www.swagger.io/support",
      "email": "support@swagger.io"
    }
  },
  "host": "echo-api.3scale.net",
  "basePath": "/v1/words",
  "schemes": [
    "http"
  ],
  "produces": [
    "application/json"
  ],
  "paths": {
    "/{word}.json": {
      "get": {
        "description": "This operation returns information about the request (path, request parameters, headers, etc.),
        "operationId": "wordsGet",
        "summary": "Returns the path of a given word",
        "parameters": [
          {
            "name": "word",
            "description": "The word related to the path",
            "type": "string",
            "in": "path",
            "required": true
          },
          {
            "name": "access_token",
            "description": "Your access token",
            "type": "string",
            "in": "query",
            "required": true
          }
        ]
      }
    }
  }
}

然后您可以像往常一样在开发人员门户中包含您的 ActiveDocs。在这种情况下,由于您要指定它们首先显示 OAuth 端点的顺序,所以它类似如下:

{% active_docs version: "2.0" services: "oauth" %}





<script type="text/javascript">
  $(function () {
    window.swaggerUi.load(); // <-- loads first swagger-ui

    // do second swagger-ui

    var url = "/swagger/spec/echo-api.json";
    window.anotherSwaggerUi = new SwaggerUi({
      url: url,
      dom_id: "another-swagger-ui-container",
      supportedSubmitMethods: ['get', 'post', 'put', 'delete', 'patch'],
      onComplete: function(swaggerApi, swaggerUi) {
        $('#another-swagger-ui-container pre code').each(function(i, e) {hljs.highlightBlock(e)});
      },
      onFailure: function(data) {
        log("Unable to Load Echo-API-SwaggerUI");
      },
      docExpansion: "list",
      transport: function(httpClient, obj) {
        log("[swagger-ui]>>> custom transport.");
        return ApiDocsProxy.execute(httpClient, obj);
      }
    });

    window.anotherSwaggerUi.load();

  });
</script>

5.2. 在 Developer Portal 中发布 ActiveDoc

在本教程结束时,您将在开发人员门户中发布您的 ActiveDocs,您的 API 文档也将是自动化的。

先决条件

  • 开发人员门户上需要使用符合 REST API 的 OpenAPI 规范(OAS)规范。

步骤

  • 将以下代码片段添加到 Developer Portal 的任何页面的内容。您必须通过 3scale 管理门户进行此操作。

    注意

    SERVICE_NAME 应为服务规格的系统名称,示例中为 pet_store

    <h1>Documentation</h1>
    <p>Use our live documentation to learn about Echo API</p>
    {% active_docs version: "2.0" services: "SERVICE_NAME" %}
    {% cdn_asset /swagger-ui/2.2.10/swagger-ui.js %} {% cdn_asset /swagger-ui/2.2.10/swagger-ui.css %} {% include 'shared/swagger_ui' %}
    <script type="text/javascript">
      $(function () {
        {% comment %}
          // you have access to swaggerUi.options object to customize its behaviour
          // such as setting a different docExpansion mode
          window.swaggerUi.options['docExpansion'] = 'none';
          // or even getting the swagger specification loaded from a different url
          window.swaggerUi.options['url'] = "http://petstore.swagger.io/v2/swagger.json";
        {% endcomment %}
        window.swaggerUi.load();
      });
    </script>

在 Developer Portal 中发布 ActiveDocs 时会考虑以下几个额外注意事项:

  • 您只能在一个页面中指定一项服务。如果要显示多个规格,最佳的做法是在不同的页面上执行该操作。
  • 此片段需要 jQuery,它默认包含在 Developer Portal 的主布局中。如果从主布局中删除 jQuery 依赖项,您必须在包含 ActiveDocs 的页面上添加此依赖项。
  • 确保管理门户中启用了 Liquid 标签。
  • Liquid tag {{ '{% active_docs 版本中使用的版本:"2.0" ' }}%} 应该与 Swagger spec 对应。

如果要从外部源获取规格,请按如下所示更改 JavaScript 代码:

$(function () {
 window.swaggerUi.options['url'] = "SWAGGER_JSON_URL";
 window.swaggerUi.load();
});

请注意,包含规范来源 的行 window.swaggerUi.options['url'] = "SWAGGER_JSON_URL"; 位于注释块之外。

验证步骤

在创建了 OpenAPI 规范将其添加到 3scale 后,到了发布规范并将其链接到开发人员门户上,供 API 开发人员使用。