发布您的 API

您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档。 信息

如下文所述，将 API 发布到您的门户，以供应用开发者使用。

API 发布概览

向门户发布 API 的过程分为两个步骤：

  1. 选择要发布到门户的 API 产品。
  2. 根据 OpenAPI 文档或 GraphQL 架构的快照呈现 API 参考文档，以便应用开发者了解您的 API。（如需详细了解快照，请参阅什么是快照？）

发布到门户的内容有哪些？

发布 API 时，系统会自动对您的门户进行以下更新：
  • API 参考文档。显示的界面取决于您是使用 OpenAPI 文档还是 GraphQL 架构发布 API。请参阅：
  • 将 API 参考页面的链接添加到 API 页面

    API 页面（包含在示例门户中）列出了发布到您的门户的所有 API 的列表（按字母顺序列出），并随附了指向相应 API 参考文档的链接。（可选）您可以自定义以下内容：

    • 为每个 API 卡片显示的图片
    • 用于标记 API 的类别，使开发者可以在 API 页面上发现相关的 API

    实时门户中的 API 页面，显示了两个类别和图像的使用情形

    • SmartDocs (OpenAPI)

    使用 OpenAPI 文档发布 API 时，SmartDocs API 参考文档会添加到您的门户。

    开发者可以查看您的 SmartDocs API 参考文档，并使用试用此 API 面板发出 API 请求并查看输出。 根据您的 OpenAPI 文档中定义的安全方法，“试用此 API”功能可用于不安全的端点或使用基本身份验证、API 密钥身份验证或 OAuth 身份验证的安全端点。对于 OAuth，支持以下流程：授权代码、密码和客户端凭据。

    API 参考文档页面，其中包含的宣传信息显示如何为 API 调用授权、移除“试用此 API”面板、下载相关规范并执行 API。

    点击 以展开“试用此 API”面板。在展开的面板中，您可以查看各种格式（如 HTTP、Python、Node.js 等）的 curl 调用和代码示例，如下所示。

    展开的“试用此 API”面板

    GraphQL 资源管理器

    使用 GraphQL 架构发布 API 时，系统会将 GraphQL 资源管理器添加到您的门户中。GraphQL 资源管理器是一个交互式平台，用于对 API 运行查询。该资源管理器基于 GraphiQL，后者是由 GraphQL Foundation 开发的 GraphQL IDE 的一个参考实现。

    开发者可以使用 GraphQL 资源管理器来浏览基于架构的交互式文档、构建和运行查询、查看查询结果以及下载架构。如果要保护对 API 的访问，开发者可以在请求标头窗格中传递授权标头。

    如需详细了解 GraphQL，请参阅 graphql.org。

    门户中的 GraphQL 资源管理器

    什么是快照？

    每个 OpenAPI 或 GraphQL 文档都用作 API 整个生命周期内的可靠来源。API 生命周期的各个阶段（从开发、发布到监控）都使用相同的文档。修改文档时，您需要了解所做的更改在 API 的其他生命周期阶段对 API 产生的影响，如修改文档时会发生什么情况？中所述。

    发布 API 时，您需要截取 OpenAPI 或 GraphQL 文档的快照来呈现 API 参考文档。该快照表示特定版本的文档。如果修改了文档，可能需要再次截取文档的快照，以反映 API 参考文档中的最新更改。

    回调网址简介

    如果您的应用需要回调网址，例如，在使用 OAuth 2.0 授权代码授权类型（通常称为“三足式 OAuth”）时，您可以要求开发者在注册应用时指定回调网址。回调网址通常指定要代表客户端应用接收授权代码的应用的网址。如需了解详情，请参阅实现授权代码授权类型。

    在向门户添加 API 时，您可以配置在应用注册期间是否需要回调网址。您可以随时按照管理 API 的回调网址中的说明修改此设置。

    注册应用时，开发者必须为所有需要回调网址的 API 输入回调网址，如注册应用中所述。

    配置 API 代理以支持“试用此 API”

    在使用 OpenAPI 文档发布 API 之前，您需要配置 API 代理，以支持在 SmartDocs API 参考文档中的“试用此 API”面板上发出请求，如下所示：

    • 向您的 API 代理添加 CORS 支持以强制执行客户端跨源请求

      CORS 是一种标准机制，允许在网页中执行的 JavaScript XMLHttpRequest (XHR) 调用与来自非源网域的资源进行交互。CORS 是通常针对所有浏览器强制执行的“同源政策”实现的解决方案。

    • 如果您使用的是基本身份验证或 OAuth2，请更新 API 代理配置

    下表汇总了 API 代理配置要求，以根据身份验证访问权限支持 SmartDocs API 参考文档中的“试用此 API”面板。

    身份验证访问权限 政策配置要求
    无或 API 密钥 向您的 API 代理添加 CORS 支持。为方便起见，请使用 GitHub 上提供的 CORS 解决方案示例，或按照为 API 代理添加 CORS 支持中所述的步骤操作。
    基本身份验证 请执行以下步骤：
    1. 向您的 API 代理添加 CORS 支持。为方便起见，请使用 GitHub 中提供的示例 CORS 解决方案，或按照向 API 代理添加 CORS 支持中所述的步骤执行操作。
    2. 在 Add CORS AssignMessage 政策中，确保 Access-Control-Allow-Headers 标头包含 authorization 属性。例如： 
      <Header name="Access-Control-Allow-Headers">
  origin, x-requested-with, accept, content-type, authorization
</Header>
      。
    OAuth2
    1. 向您的 API 代理添加 CORS 支持。为方便起见，请使用 GitHub 中提供的示例 CORS 解决方案，或按照向 API 代理添加 CORS 支持中所述的步骤执行操作。
    2. 在 Add CORS AssignMessage 政策中，确保 Access-Control-Allow-Headers 标头包含 authorization 属性。例如： 
      <Header name="Access-Control-Allow-Headers">
  origin, x-requested-with, accept, content-type, authorization
</Header>
      。
    3. 更正 OAuth2 政策中的不符合 RFC 规范的行为。为方便起见，请使用 GitHub 上提供的 OAuth2 解决方案示例，或执行以下步骤：
      • 确保将 OAuth2 政策中的 <GrantType> 元素设置为 request.formparam.grant_type（表单参数）。有关详情，请参阅 <GrantType>。
      • 确保将 OAuth2 政策中的 token_type 设置为 Bearer，而不是默认值 BearerToken。

    探索 API 目录

    如需查看 API 目录，请执行以下操作：
    1。选择发布 > 门户，然后选择您的门户。
    2. 在门户着陆页上点击 API 目录 (API catalog)。
    或者，您可以在顶部导航栏的门户下拉菜单中选择 API 目录 (API catalog)。

    API 目录中的 API 标签页显示了已添加到您的门户的 API 列表。

    API 标签页，其中显示与 API 有关的信息，包括名称、说明、可见性、类别、相关规范和修改时间

    如上图所示，您可以通过 API 标签页执行以下操作：

    向门户添加 API

    如需向您的门户添加 API，请执行以下操作：

    1. 访问 API 目录。
    2. 点击 API 标签页（如果尚未选择）。

    3. 点击 +。

      系统会显示“将 API 产品添加到目录”对话框。

    4. 选择要添加到门户的 API 产品。

    5. 点击下一步。
      此时将显示 API 详细信息页面。

    6. 配置 API 参考文档内容及其在门户中的可见性：

      字段 说明
      已发布选择发布，以将 API 发布到您的门户。如果您还没准备好发布 API，请取消选中该复选框。您稍后可以按照在门户上发布或取消发布 API 中的说明更改此设置。
      显示标题 更新目录中显示的 API 的标题。默认情况下，系统会使用 API 产品名称。您可以稍后更改显示标题，如修改显示标题和说明中所述。
      显示说明 更新目录中显示的 API 的说明。默认情况下，系统会使用 API 产品说明。您可以稍后更改显示说明，如修改显示标题和说明中所述。
      要求开发者指定回调网址如果您希望要求应用开发者指定回调网址，请启用此 API。您可以稍后添加或更新回调网址，如管理 API 的回调网址中所述。
      API 文档 如需使用 OpenAPI 文档，请执行以下操作：
      1. 选择 OpenAPI 文档。
      2. 点击选择文档。
      3. 执行以下步骤之一：
        • 点击我的规范标签，然后从规范库中选择一个规范。
        • 点击上传文件标签页，然后上传文件。
        • 点击从网址导入标签页，然后从网址导入规范。
      4. 点击选择。

      如需使用 GraphQL 架构，请执行以下操作：

      1. 选择 GraphQL 架构。
      2. 点击选择文档。
      3. 导航到 GraphQL 架构，并选择它。
      4. 点击选择。

      或者，您也可以选择无文档，然后在添加 API 后稍后添加文档，如管理文档的快照中所述。

      API 可见性

      如果您尚未注册受众群体管理功能的 Beta 版，请选择以下选项之一：

      • 匿名用户：允许所有用户查看 API。
      • 注册用户：仅允许已注册的用户查看 API。

      如果您已注册受众群体管理功能的 Beta 版，请选择以下选项之一：

      • 公开（对所有人可见）：允许所有用户查看 API。
      • 经过身份验证的用户：仅允许已注册的用户查看 API。
      • 选定受众群体：选择您希望能够查看 API 的特定受众群体。

      您稍后可以按照管理 API 在门户中的公开范围中的说明，管理受众群体的公开范围。

      封面图片 如需在 API 页面上显示 API 卡片的图片，请点击选择图片。在选择图片对话框中，选择一个现有图片、上传新图片或提供外部图片的网址，然后点击选择。预览 API 缩略图，然后点击选择。您可以稍后添加图片，如管理 API 卡片的图片中所述。
      类别

      添加将要标记 API 的类别，使应用开发者可在 API 页面上发现相关的 API。如需识别某个类别，请执行以下操作：

      • 从下拉列表中选择类别。
      • 输入新类别的名称，然后按 Enter 键即可添加新类别。新类别便会添加到“类别”页面，并且在添加或修改其他 API 时可用。

    7. 点击保存。

    管理文档的快照

    发布 API 后，您可以随时截取 OpenAPI 或 GraphQL 文档的新快照，以更新在门户上发布的 API 参考文档。

    如需管理文档的快照，请执行以下操作：

    1. 访问 API 目录。
    2. 点击 API 标签页（如果尚未选择）。
    3. 点击要修改的 API 对应的行。
    4. 检查快照状态。如果快照已过期，系统会显示以下消息：
      图标和表示快照已过期的消息
    5. 点击 “修改”图标。
    6. 执行以下一项任务：
      • 如需刷新已过期的 OpenAPI 文档的快照，请点击刷新快照。
      • 如需更改用于生成 API 文档的文档，请在 API 文档下方点击选择文档，然后选择新文档。
    7. 点击保存。

    API 参考文档从文档呈现，并将其添加到“API 参考”页面。快照状态会更新为当前状态：

    图标和表示快照是最新快照的消息

    在您的门户上发布或取消发布 API

    如需在您的门户上发布或取消发布 API，请执行以下操作：

    1. 访问 API 目录。
    2. 点击 API 标签页（如果尚未选择）。
    3. 点击要修改的 API 对应的行。
    4. 点击 “修改”图标。
    5. 在“API 详细信息”下，选择或取消选择已发布（在目录中列出），以分别在您的门户上发布或取消发布 API。
    6. 点击保存。

    管理门户中 API 的公开范围

    通过为以下各项授予访问权限，管理门户中 API 的公开范围：

    如需管理门户中 API 的公开范围，请执行以下操作：

    1. 访问 API 目录。
    2. 点击 API 标签页（如果尚未选择）。
    3. 点击要修改的 API 对应的行。
    4. 点击 “修改”图标。
    5. 在 API 公开范围下，选择以下选项之一：

    6. 选择公开范围设置。如果您已注册受众群体功能的 Beta 版，请选择以下选项之一：

      • 公开（对所有人可见）：允许所有用户查看页面。
      • 经过身份验证的用户：只允许注册用户查看页面。
      • 已选择的受众群体会选择您希望能够查看相应网页的特定受众群体。请参阅管理门户的受众群体。
      否则，请选择以下选项之一：
      • 匿名用户：允许所有用户查看页面。
      • 已注册的用户：只允许注册用户查看页面。

    7. 点击提交。

    管理 API 的回调网址

    管理 API 的回调网址。请参阅回调网址简介。

    如需管理 API 的回调网址，请执行以下操作：

    1. 访问 API 目录。
    2. 点击 API 标签页（如果尚未选择）。
    3. 点击要修改的 API 对应的行。
    4. 点击 “修改”图标。
    5. 在“API 详细信息”下，选择或取消选择已发布（在目录中列出），以分别在您的门户上发布或取消发布 API。
    6. 点击保存。

    管理 API 卡片的图片

    通过添加图片或更改当前图片，管理 API 页面上的 API 卡片中显示的图片。

    如需管理 API 卡片的图片，请执行以下操作：

    1. 访问 API 目录。
    2. 点击 API 标签页（如果尚未选择）。
    3. 点击要修改的 API 对应的行。
    4. 点击 “修改”图标。

    5. 在“API 详细信息”下：

      • 点击选择图片以选择或上传图片（如果您当前未选择图片）。
      • 点击更改图片以选择或上传其他图片。
      • 点击图片中的 x 可将其移除。

    6. 点击保存。

    使用类别标记 API

    您可以通过以下方式之一使用类别标记 API：

    • 如下所述，在修改 API 时管理要标记其 API 的类别。
    • 在修改类别时管理针对类别标记的 API。

    要在修改 API 时针对类别标记 API，请执行以下操作：

    1. 访问 API 目录。
    2. 点击 API 标签页（如果尚未选择）。
    3. 点击要修改的 API 对应的行。
    4. 点击 “修改”图标。
    5. 点击类别字段并执行以下某个步骤：
      • 从下拉列表中选择类别。
      • 输入新类别的名称，然后按 Enter 键即可添加新类别。新类别便会添加到“类别”页面，并且在添加或修改其他 API 时可用。
    6. 重复以上操作即可针对更多类别标记 API。
    7. 点击保存。

    修改显示标题和说明

    要修改显示标题和说明，请执行以下操作：

    1. 访问 API 目录。
    2. 点击 API 标签页（如果尚未选择）。
    3. 点击要修改的 API 对应的行。
    4. 点击 “修改”图标。
    5. 根据需要修改显示标题和显示说明字段。
    6. 点击保存。

    从门户中移除 API

    如需从您的门户中移除 API，请执行以下操作：

    1. 访问 API 目录。
    2. 选择 API（如果尚未选择）。
    3. 将光标置于列表中的 API 上以显示操作菜单。
    4. 点击 “修改”图标。

    管理用于发现相关 API 的类别

    使用类别标记 API，使应用开发者可在实时门户的 API 页面上发现相关 API。添加和管理类别，如以下部分所述。

    浏览“类别”页面

    要查看“类别”页面，请执行以下操作：

    1. 选择发布 > 门户，然后选择您的门户。
    2. 在门户着陆页上点击 API 目录 (API catalog)。

      或者，您可以在顶部导航栏的门户下拉菜单中选择 API 目录 (API catalog)。

    3. 点击类别标签。

    API 目录中的“类别”标签页会显示已为您的门户定义的类别列表。

    显示类别名称以及已分配的 API 的名称和总数的类别标签页

    如上图所示，您可以通过 API 页面执行以下操作：

    添加类别

    您可以通过以下任一方式添加类别：

    新类别便会添加到“类别”页面，并且在添加或修改其他 API 时可用。

    要手动添加类别，请执行以下操作：

    1. 访问“类别”页面。
    2. 点击 +。
    3. 输入新类别的名称。
    4. （可选）选择一个或多个要针对类别进行标记的 API。
    5. 点击创建。

    修改类别

    如需修改类别，请执行以下操作：

    1. 访问“类别”页面。
    2. 点击 。
    3. 修改类别的名称。
    4. 添加或移除 API 标记。
    5. 点击保存。

    删除类别

    如果删除类别，则该类别的所有 API 标记也将被删除。

    要删除类别，请执行以下操作：

    1. 访问“类别”页面。
    2. 将光标置于您要修改的类别上方以显示操作菜单。
    3. 点击 。
    4. 修改类别的名称。
    5. 添加或移除 API。
    6. 点击保存。

    排查已发布的 API 的问题

    以下部分提供了相关信息来帮助您排查已发布的 API 中存在的特定错误。

    错误：使用“试用此 API”时返回“未能获取”错误

    使用“试用此 API”时，如果系统返回 TypeError: Failed to fetch 错误，请考虑以下可能的原因和解决方法：

    • 对于混合内容错误，错误可能是由已知的 Swagger 界面问题引起。 一种可能的解决方法是确保在 OpenAPI 文档的 schemes 定义中在 HTTP 前面指定 HTTPS。例如：

      schemes:
   - https
   - http

    • 对于跨源资源共享 (CORS) 限制错误，请确保您的 API 代理支持 CORS。 CORS 是一种支持客户端跨源请求的标准机制。请参阅配置 API 代理以支持“试用此 API”。

    错误：“Access-Control-Allow-Origin”标头包含多个“'*, *”值，但仅允许一个值

    使用“试用此 API”时，如果 Access-Control-Allow-Origin 标头已存在，您可能会收到以下错误消息：

    The 'Access-Control-Allow-Origin' header contains multiple values '*, *', but only one is allowed.

    如需更正此错误，请修改 AssignMessage 政策以使用 <Set> 来设置 CORS 标头，而不是 <Add>，如下面的代码段所示。如需了解详情，请参阅相关的社区文章。 

    <AssignMessage async="false" continueOnError="false" enabled="true" name="add-cors">
    <DisplayName>Add CORS</DisplayName>
    <FaultRules/>
    <Properties/>
    <Set>
        <Headers>
            <Header name="Access-Control-Allow-Origin">{request.header.origin}</Header>
            <Header name="Access-Control-Allow-Headers">origin, x-requested-with, accept, content-type, authorization</Header>
            <Header name="Access-Control-Max-Age">3628800</Header>
            <Header name="Access-Control-Allow-Methods">GET, PUT, POST, DELETE</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

    错误：不允许请求标头字段

    使用“试用此 API”时，如果您收到 Request header field not allowed 错误（类似于以下示例），则可能需要更新 CORS 政策支持的标头。例如：

    Access to XMLHttpRequest ... has been blocked by CORS policy: Request header field
content-type is not allowed by Access-Control-Allow-Headers in preflight response

    在此示例中，您需要将 content-type 标头添加到 CORS AssignMessage 政策中的 Access-Control-Allow-Headers 部分，如将 Add CORS 政策附加到新的 API 代理中所述。

    错误：使用 OAuth2 调用 API 代理时访问遭拒

    Apigee 的 OAuthV2 政策会返回包含某些不符合 RFC 规范的属性的令牌响应。例如，该政策将返回值为 BearerToken 的令牌，而不是预期符合 RFC 规范的值 Bearer。使用“试用此 API”时，无效的 token_type 响应可能会导致 Access denied 错误。

    如需更正此问题，您可以创建 JavaScript 或 AssignMessage 政策，以将政策输出转换为符合规范的格式。有关详情，请参阅不符合 RFC 规范的行为。