在 Developer Portal 中提供 API

Red Hat 3Scale 2-saas

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

摘要

本指南记录了红帽 3scale 2 销售中开发人员门户的使用。

前言

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

使开源包含更多

红帽承诺替换我们的代码、文档和网页属性中存在问题的语言。我们从这四个术语开始: master、slave、blacklist 和 whitelist。这些更改将在即将发行的几个发行本中逐渐实施。详情请查看我们的 CTO Chris Wright 信息

部分 I. OpenAPI 规格

第 1 章 OpenAPI 规范简介

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

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

先决条件

  • 定义您的 API 的 OpenAPI 文档。
  • 3scale 2-saas 实例租户凭证(tokenprovider_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-saas 实例租户凭证(tokenprovider_key)。

2.1. OpenAPI 规范 3.0 使用 3scale

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

  • swagger-ui Developer Portal 中已更新来支持 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 实施依赖于 Documentation 页面中是否存在一个 {% active_docs version: "2.0" %} 临时标签。随着 3scale 中引入对 Swagger 2.2.10 的支持,实施方法会更改为多个 cdn_assetinclude 弹性标签。

注意

对于 Swagger UI 2.1.3 及更早版本,{ProductNameShort} 继续使用旧的 active_docs 移动标签方法调用 UI。

先决条件

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

流程

  1. 登录您的 3scale 管理门户。
  2. 进入 Developer PortalDocumentation 页面,或者导航到您要更新 Swagger UI 的页面
  3. 在代码窗格的 Draft 选项卡中,将 {% active_docs version: "2.0" %} 标签替换为 cdn_asset 操作标签和新的部分 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 章 Update To ActiveDocs 2.0

注意

本节的详细信息仅供参考。这个选项不再被支持,您应该尽早考虑从这个配置中迁移。

在本教程结束时,您将了解需要对 ActiveDocs 配置进行哪些更改才能成功升级到 2.0 版本。

有关 ActiveDocs 2.0 配置的说明,请参阅 Adding Specifications to 3scale。有关规格的具体差异可在官方 Swagger 1.2 到 2.0 迁移指南 中找到。本文只记录了升级到 ActiveDocs 2.0 的额外步骤。

注意

如果您的 ActiveDocs spec 仍处于 1.0 版本,请首先将其转换为 1.2 版本。

3.1. 第 1 步:对您的规格应用适当的命名规则

进入管理门户中的 API → ActiveDocs 选项卡。这将让您进入服务规格的列表。您应该已添加了服务规格(请参阅 创建服务规格)。

Naming your specification

您应该应用适当的名称以在开发人员门户中达到所需的效果 - ActiveDocs API 列表的标题将显示为"系统名称:Description"。您可能需要仅通过复制 JSON spec 和其他字段来重新创建 spec,因为系统名称是只读的。

3.2. 第 2 步: 修改服务规格

ActiveDocs 2.0 的规范与版本 1.2 相比有一些重要变化。详情请参阅 Swagger 1.2 到 2.0 迁移指南。最重要的变化是:

  • "swaggerVersion": "1.2" root 元素现在是 "swagger": "2.0",它是一个必填字段。
  • "info"对象变为必填对象。
  • "apiVersion": "1.0" 变为必需,现在是 "info" 对象的一部分: "info": { "version": "1.0", …​ }
  • "info"对象中的描述变得非必要。
  • 如果存在 "license" 对象,则需要许可证名称字段。
  • "basePath": "https://example.com/api" 字段被分成三个字段: "host": "example.com""basePath": "/api""schemes": [ "http" ]。这些字段都不是必需的。

3.3. 第 3 步: 将 Javascript 和 HTML 内容添加到 CMS 页面

将以下代码片段添加到 CMS 页面,其中 SERVICE_NAME 应为服务规格的系统名称。

<h1>Documentation</h1>
<p>Use our live documentation to learn about Echo API </p>
{% active_docs version: "2.0" services: "SERVICE_NAME" %}
<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>

如果要在一个页面中包含多个 Swagger specs,您可以使用这个自定义片断:

{% 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/sentiment.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 Sentiment-SwaggerUI");
      },
      docExpansion: "list",
      transport: function(httpClient, obj) {
        log("[swagger-ui]>>> custom transport.");
        return ApiDocsProxy.execute(httpClient, obj);
      }
    });
     window.anotherSwaggerUi.load();
   });
</script>

3.4. 第 4 步:使用 ActiveDocs 1.2 测试您的 API

  • 记得在 CMS 配置页面中启用 Liquid 标签。

    Enable Liquid tags
  • 最后,在预览模式中,关闭右侧垂直边栏以查看 ActiveDocs 2.0。
注意

新样式与较新的 Swagger 规范(2.0)兼容。如果您想改变外观和感觉,则必须覆盖风格。由于 Swagger 的 CSS 与 HTML 一起包含,因此您必须定义更具体性或带有 ! importantant 标签的样式。

第 4 章 将 ActiveDocs 添加到 3scale

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

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

4.1. 在 3scale 中设置 ActiveDocs

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

先决条件

  • 定义您的 API 的 OpenAPI 文档。
  • 3scale 2-saas 实例租户凭证(tokenprovider_key)。

流程

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

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

  2. 点击 Create a new spec

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

    • 名称
    • 系统名称.这需要引用 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 new specification view

第 5 章 如何编写 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 的服务器中自动生成客户端库。支持使用多种现代语言创建客户端侧库。

5.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

5.2. OpenAPI 文档示例:Petstore API

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

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

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

Petstore API 方法

Petstore API 由 4 个方法组成:

  • GET /api/pets - 从系统返回所有宠物
  • POST /api/pets - 在存储中创建新宠物
  • GET /api/pets/{id} - 根据单个 ID 返回宠物
  • 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}"

5.3. 其他 OAS 规格信息

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

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

OAS 对象

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

警告

主机必须是域,而非 IP 地址。3scale 将针对开发人员门户发出的请求代理到您的主机,并呈现结果。出于安全原因,这需要您的 主机和 basePath 端点获得 3scale 批准。您只能声明自己的主机。如果检测到您正在代理不属于您的域,3scale 保留终止您的帐户的权利。这意味着本地主机或任何其他通配符域不起作用。

info 对象

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

paths 对象

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

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

目前 OAS 支持以下 dataType:

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

5.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。

5.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 字段是一个 OAS 扩展,它在 ActiveDocs 域外被忽略。

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

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

Auto-fill when not logged-in

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

Auto-fill when logged-in

第 6 章 ActiveDocs 和 OAuth

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

先决条件

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

第一个示例是在 3scale 规格中使用 OAuth 2.0 客户端凭证流的 API。此 API 接受任何路径,并返回有关请求的信息(路径、请求参数、标头等)。Echo API 只能通过使用有效的访问令牌来访问。API 用户只能在交换访问令牌的凭证(client_idclient_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>

6.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 标签 {{ '{% active_docs version: "2.0" ' }}%} 中使用的版本应当与 Swagger 规格的版本对应。

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

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

请注意,包含规格源 window.swaggerUi.options['url'] = "SWAGGER_JSON_URL"; 的行不在注释块之外。

验证步骤

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

第 7 章 APIcast 自管理(旧版本)和 OAuth 2.0

注意

本节的详细信息仅供参考。这个选项不再被支持,您应该尽早考虑从这个配置中迁移。

所有 OAuth 调用都必须使用 SSL。

本文档引用了旧版本的 APIcast 的 OAuth,其中包含 Nginx 可下载的配置文件。请注意,自 2017 年 5 月起,此版本在 GUI 中不再可用于新客户。有关 APIcast 最新版本中的 OAuth 支持详情,请参阅 此处

本教程显示了设置 APIcast 自我管理并带有 3scale 的 OAuth 扩展使 APIcast 充当 OAuth 2.0 提供程序的必要步骤。

目前,APIcast 中仅提供授权代码(服务器端)授权流。但是,您可以找到此 GitHub 仓库 上所有其他流的配置模板。

7.1. 先决条件

因为 3scale 不包含您验证的用户的任何详情,因此为了使用 OAuth 2.0 与 3scale 集成,我们需要在一侧处理用户身份验证。为此,您必须为 APIcast 发送用户授权应用程序的页面的 URL。此页面应当位于登录之后,以便正确识别和验证用户。用户通过身份验证并且应用获得授权后,您应该使用用户授权的结果重新重定向到 APIcast。

当 APIcast 将用户重定向到授权 URL 时,它将发送以下参数和请求:

  • scope: 应用所属的计划 ID。应用计划在 3scale 中定义范围。
  • state: APIcast 和 API 之间共享的哈希值,用于识别请求并确保其真实性。
  • tok: 访问令牌的值,将在应用获得授权后提供给用户。令牌只有在为授权代码交换时才会发布。如果没有交换授权代码,访问令牌将在 10 分钟后过期。

如果用户成功标识并授权应用,授权页面应重定向到 APIcast 上的端点。默认情况下,它位于 /callback,但可轻松在 APIcast 配置文件中更改以满足您的需要。

看一下如何设置此设置。

7.2. OAuth 配置

要继续安装,您需要遵循与基本 APIcast 集成相同的步骤,以配置 API 并定义方法和 enpdoint。您可以在链接中找到这些步骤: 安装 APIcast 文档。另外,您需要确保遵循以下步骤:

7.2.1. 第 1 步:编辑集成设置

根据以下屏幕截图,您需要将"Production Deployment Option"设置为自助管理网关,因为 OAuth 目前在 APIcast 托管上不可用。

OAuth APIcast Settings

在同一页面中,您还需要将"身份验证"设置为 OAuth 2.0。

7.2.2. 第 2 步: 排除您的 OAuth 授权端点

当用户需要登录您的服务以进行身份验证并提供同意时,将会显示此 URL。

APIcast OAuth 扩展允许 APIcast 充当 OAuth 提供程序。但是,您仍然需要为用户提供授权端点,以便自己进行身份验证并批准/拒绝第三方应用访问。此授权端点应在登录之后,以便能识别和验证用户。批准完成后,您需要将登录的用户重定向到 APIcast 上的回调端点,以便它处理工作流的其余部分。

7.2.3. 第 3 步: 下载 APIcast 配置文件

3scale 根据您输入到集成页面的数据,自动生成使用 APIcast 作为 API 网关和 OAuth 提供程序所需的文件。输入所有必需信息后,您可以下载这些文件并将其安装在您自己的 APIcast 实例上。下载的 zip 文件将为每个定义的服务包含一个单独的 *.lua 文件,以及用于支持 OAuth 握手的 lua 文件和在服务间共享的 nginx_\*.conf 文件。

如果您定义了多个服务,用户下载配置文件将收到 zip 文件,其中 Lua 文件将仅包含与其可访问的服务对应的服务 令牌。这样,Provider Key 只会为全管理员保存机密。

7.3. 运行您自我管理的 APIcast 实例(生产)

如果您熟悉 NGINX,则在本地启动并运行 APIcast 不需要很长时间。请注意,您的 NGINX 安装必须具有 Lua 插件,对于某些 OAuth 2.0 授权类型,还必须在服务器上安装 Redis。

如果您不熟悉 NGINX,建议您安装 OpenResty,这是一个非常好的 Web 应用程序,基本上是标准 NGINX 核心的捆绑包,几乎包含您需要构建的所有第三方 NGINX 模块。

7.3.1. 第 1 步:安装依赖项(用于 Ubuntu)

对于 Debian/Ubuntu linux 发行版,您应该使用 apt-get 安装以下软件包:

sudo apt-get install libreadline-dev libncurses5-dev libpcre3 libpcre3-dev libssl-dev perl
sudo apt-get build-dep nginx

对于不同的系统,请查看 OpenResty 文档。

7.3.2. 第 2 步:编译和安装 OpenResty

下载代码并编译,使用您需要的版本更改 VERSION(我们通常建议运行最新的稳定版本)。

wget http://agentzh.org/misc/nginx/ngx_openresty-VERSION.tar.gz
tar -zxvf ngx_openresty-VERSION.tar.gz
cd ngx_openresty-VERSION/

./configure --prefix=/opt/openresty --with-luajit --with-http_iconv_module -j2

make
make install

此时,您已使用 OpenResty 捆绑包安装了 NGINX 和 Lua。

7.3.3. 第 3 步:安装 Redis

在 APIcast 服务器中下载并安装 Redis(我们建议始终使用最新的稳定版本)。

tar zxvf  redis-VERSION.tar.gz
cd redis-VERSION
make
sudo make install

要安装并运行 Redis 服务器,请运行以下命令,接受所有默认值:

sudo ./utils/install_server.sh

7.3.4. 第 4 步:从 3scale 下载 APIcast 配置

请注意,当前只有授权代码(服务器端)授权流配置可从 Integration 页面下载。但是,您可以 在此处 查找 GitHub 存储库上的所有其他流的配置模板。

单击 Download 按钮,从 3scale 下载 APIcast 配置文件。这会为您提供一个 zip 文件,其中包含六个文件:

  • authorize.lua - 此文件包含授权客户端、将 end_user 重定向到 OAuth 登录页面、生成访问令牌以及检查返回 URL 是否与 API 买方指定的 URL 相匹配的逻辑。它在 /authorize 端点命中时运行。
  • authorized_callback.lua - 此文件包含将 API 最终用户重定向到 API 买家重定向 URL 的逻辑。作为 API 供应商,您需要在用户成功登录并授权 API 买家请求访问后调用此端点。此文件在您的 Web 应用调用 /callback 端点时执行。
  • get_token.lua - 此文件包含返回由 client_id 标识的客户端的访问令牌的逻辑。它在调用 /oauth/token 端点时执行。
  • nginx_*.conf - .conf 是典型的 NGINX 配置文件。如果您已在运行 NGINX,可以随意对其进行编辑或将其复制到现有的 .conf 中。
  • nginx_*.lua - 此文件包含您在 Web 界面上定义的逻辑,用于跟踪各种指标和方法的使用情况。
  • threescale_utils.lua

7.3.5. 第 5 步:启动和停止 APIcast

唯一需要做的是启动 APIcast。执行此操作的方法有很多,但最直接的方法是:

sudo /opt/openresty/nginx/sbin/nginx -p /opt/openresty/nginx/ -c /opt/openresty/nginx/conf/YOUR-CONFIG-FILE.conf

这个示例假设 APIcast 的工作目录是 /opt/openresty/nginx,这是您在安装期间为配置 --prefix=/opt/openresty 传递的路径。您可以对其进行更改,但请注意用户特权。

这个示例还假设 3scale 生成的 .conf 放置到 /opt/openresty/nginx/conf/。当然,您应该将文件和目录放在最适合您的生产环境的位置,以及启动和停止作为系统守护进程的进程,而不是直接执行二进制文件。

停止正在运行的 APIcast 实例:

sudo /opt/openresty/nginx/sbin/nginx -p /opt/openresty/nginx/ -c /opt/openresty/nginx/conf/YOUR-CONFIG-FILE.conf -s stop

选项 -s 允许您向 nginx 传递信号。停止的进程是 .pid 存储在 /opt/openresty/nginx/logs/nginx.pid 中的进程。

APIcast 日志默认位于同一目录中: /opt/openresty/nginx/logs/。设置整个过程时,请检查 error.log。

7.3.6. 第 6 步: 测试 OAuth 流

测试您的 API 现在支持 OAuth 的最佳方法是使用 Google 的 OAuth play 台: https://developers.google.com/oauthplayground

您需要为要用于测试此条件的应用设置重定向 URL,以将其设置为 google OAuth Playground URL: https://developers.google.com/oauthplayground

然后,您可以按照以下屏幕截图所示填写设置:

Google OAuth Playground Settings

授权和令牌端点 URL 是来自 APIcast 实例的 URL。在范围内,放置应用的应用计划的名称(例如:"Default")。

单击 Authorize API,这会将您重定向到您的登录 URL。然后,登录到应用程序中的用户帐户并授权应用程序。完成后,您将通过授权代码重新重定向到 Google OAuth Playground。为访问令牌交换它。现在,您有一个访问令牌来调用 API 上的受保护端点。

现在,您可以向 API 发出请求,但将 API 后端主机名(在 APIcast 实例示例中为 echo-api.3scale.net)替换为 APIcast 实例的主机名,并添加 access_token 参数。例如:

curl -X GET "http://YOUR_APICAST_HOST/read?access_token=YOUR_ACCESS_TOKEN"

现在,您的 API 与 3scale 集成。