在开发者门户中提供 API

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 标签。

您可以在 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 API 管理的 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"; 在注释块之外。