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

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

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

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

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

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

您可以将 OAS 3.0 规格添加到 ActiveDocs 中，并在开发者门户中显示它们，请考虑以下点：

{% 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>

{% 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>

您可以将 OAS 2.0 规格添加到 ActiveDocs 中，并在 Developer Portal 中显示它们，请考虑以下点：

对 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>

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

以前在 3scale 开发人员门户中实现的 Swagger UI 2.1.3 需要在 Documentation 页中存在一个 {% active_docs version: "2.0" %} liquid 标签。随着 3scale 中对 Swagger 2.2.10 的支持，实施方法会更改为多个 cdn_asset 和 include liquid 标签。

导航到管理门户中的 API → ActiveDocs 选项卡。这将导致您进入您的服务规格列表。您应该已经添加了服务规格（请参阅 创建服务规格）。

您应该在 Developer Portal 中应用适当的名称来实现所需的效果 - ActiveDocs API 列表的标题将显示为 "System name: Description"。您可能需要通过复制 JSON spec 和其他字段再次重新创建 spec，因为系统名称是只读的。

与版本 1.2 相比，ActiveDocs 2.0 的规格对版本有一些重要更改。有关详细信息，请参阅 Swagger 1.2 到 2.0 迁移指南。最重要的更改是：

将以下代码片段添加到 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>

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

您可以通过点您提供服务规格的名称来预览您的 ActiveDocs 看起来，例如 Pet Store。即使规格尚未发布，您也可以执行此操作。

以下是 ActiveDoc 的意义：

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 的 OpenAPI 规格 3.0 使用”。

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

3scale 通过几种方法扩展 OAS，以适应开发者门户互动 API 文档所需的特定功能：

要从原始源读取规格，请参阅 OpenAPI 规格。

在 OAS 网站上，定义了 API 的 OpenAPI 文档的多个示例。如果您想通过示例了解，可以按照 OAS API 团队的 Petstore API 示例进行操作。

Petstore API 是一个极其简单的 API。它被称为学习工具，不适用于生产环境。

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

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

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}"

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

OAS 依赖于资源声明，它映射到通过 JSON 编码的哈希。使用 Petstore swagger.json 文件作为示例，并了解每个对象。

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

目前，OAS 支持以下 dataTypes ：

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

自动填充 API 凭证是 OAS 在 3scale ActiveDocs 中非常有用的扩展。您可以根据 API 验证模式，使用以下值定义 x-data-threescale-name 字段：

"parameters": [
  {
    "name": "user_key",
    "in": "query",
    "description": "Your API access key",
    "required": true,
    "schema": {
      "type": "string"
    },
    "x-data-threescale-name": "user_keys"
  }
]

对于使用 x-data-threescale-name 声明的参数，当您登录开发人员门户时，您会看到带有 5 个最新的键、用户键、App Id 或 App 键的下拉列表，具体取决于规格中配置的值。因此，您可以在不需要复制并粘贴值的情况下自动填充输入：

第一个示例是在 3scale 规格中使用 OAuth 2.0 客户端凭证流的 API。此 API 接受任何路径并返回有关请求的信息（path、请求标头、标头等）。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_id 和 client_secret，这可从对签名用户的 3scale 值填充，以及 grant_type。

然后，在 Echo API 的 ActiveDocs 规格中，添加 access_token 参数，而不是 client_id 和 client_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
          }
        ]
      }
    }
  }
}

然后您可以在 Developer Portal 中包含 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>

在本教程结束时，您将在开发人员门户中发布您的 ActiveDoc，您的 API 文档将自动执行。

在开发者门户中发布 ActiveDocs 时，这些额外注意事项：

如果要从外部来源获取您的规格，请按如下所示更改 JavaScript 代码：

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

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

因为 3scale 不包含您进行身份验证的用户的任何详情，以便使用 OAuth 2.0 与 3scale 集成，因此我们要求您自行处理用户身份验证。为此，您必须提供 APIcast 可以向用户授权应用程序的页面的 URL。此页面应位于登录后，以便正确识别和验证用户。用户通过身份验证并授权应用后，您应该通过用户授权的结果重新重定向到 APIcast。

当 APIcast 将用户重定向到授权 URL 时，它将发送以下参数以及请求：

如果用户成功识别自己并授权应用程序，授权页面应重定向到 APIcast 上的端点。默认情况下，这位于 /callback 中，但可以在 APIcast 配置文件中轻松更改以适合您的需求。

进行查找并查看如何设置此设置。

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

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

根据下面的屏幕截图，您需要将"产品部署选项"设置为自我管理网关，因为 OAuth 目前在 APIcast 托管上不可用。

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

如果您熟悉 NGINX，则不应花费很长时间才能在本地启动并运行 APIcast。请注意，您的 NGINX 安装必须具有 Lua 插件，以及某些 OAuth 2.0 授权类型，您还必须在服务器上安装 Redis。

如果您不熟悉 NGINX，我们建议您安装 OpenResty，它是一个 fantastic web 应用程序，它基本上是标准 NGINX 内核的捆绑包，其中几乎是需要构建的所有第三方 NGINX 模块。

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

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

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

sudo ./utils/install_server.sh

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

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

7.3.6. 第 6 步：测试您的 OAuth 流

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

您需要为您要用来测试它的应用程序设置重定向 URL： https://developers.google.com/oauthplayground

然后，您可以按照以下屏幕截图填写设置：

授权和令牌端点 URL 是 APIcast 实例的 URL。在范围内，为应用程序放置应用计划的名称（如 "Default"）。

点 Authorize API，这将把您重定向到您的登录 URL。然后，登录到应用程序上的用户帐户并授权应用程序。完成后，您将使用授权代码重定向到 Google OAuth Playground。将其交换用于访问令牌。现在，您有一个访问令牌才能在 API 上调用受保护的端点。

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

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

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