<ph type="x-smartling-placeholder"></ph>
您正在查看 Apigee Edge 文档。
转到
Apigee X 文档。 信息
<ph type="x-smartling-placeholder">
如下文所述,将 API 发布到您的门户,以供应用开发者使用。
API 发布概览
向门户发布 API 的过程分为两个步骤:
- 选择要发布到门户的 API 产品。
- 根据 OpenAPI 文档或 GraphQL 架构的快照呈现 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”面板。在展开的面板中,您可以查看各种格式(如 HTTP、Python、Node.js 等)的 curl 调用和代码示例,如下所示。
GraphQL 资源管理器
使用 GraphQL 架构发布 API 时,系统会将 GraphQL 资源管理器添加到您的门户中。GraphQL 资源管理器是一个交互式平台,用于对 API 运行查询。该资源管理器基于 GraphiQL,后者是由 GraphQL Foundation 开发的 GraphQL IDE 的一个参考实现。
开发者可以使用 GraphQL 资源管理器来浏览基于架构的交互式文档、构建和运行查询、查看查询结果以及下载架构。如果要保护对 API 的访问,开发者可以在请求标头窗格中传递授权标头。
如需详细了解 GraphQL,请参阅 graphql.org。
什么是快照?
每个 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 支持中的步骤操作。 |
基本身份验证 | 请执行以下步骤:
|
OAuth2 |
|
浏览 API 目录
如需查看 API 目录,请执行以下操作: 1.选择发布 >门户,然后选择您的门户。 2. 点击门户首页上的 API 目录。 或者,您也可以在顶部导航栏的门户下拉菜单中选择 API 目录。
API 目录中的 API 标签页显示了已添加到您的门户的 API 列表。
如上图所示,您可以通过 API 标签页执行以下操作:
- 查看门户上可用的 API 的详细信息
- 向您的门户添加 API
- 通过执行以下一项或多项任务,在您的门户上修改 API:
- 从门户中移除 API
- 管理用于发现相关 API 的类别
- 快速识别已过时或已从规范存储区中删除的规范
- 快速识别“孤立”状态关联 API 产品已从 Edge 中移除的 API,然后重新创建 API 产品或从门户中删除 API
向门户添加 API
如需向您的门户添加 API,请执行以下操作:
- 访问 API 目录。
- 点击 API 标签页(如果尚未选择)。
点击 +。
系统会显示“将 API 产品添加到目录”对话框。
选择要添加到门户的 API 产品。
点击下一步。 系统会显示“API 详细信息”页面。
配置 API 参考文档内容及其在门户中的可见性:
字段 说明 已发布 选择发布,以将 API 发布到您的门户。如果您还没准备好发布 API,请取消选中该复选框。您以后可以按照在门户上发布或取消发布 API 中的说明更改设置。 显示标题 更新目录中显示的 API 的标题。默认情况下,系统会使用 API 产品名称。您可以稍后更改显示标题,如修改显示标题和说明中所述。 显示说明 更新目录中显示的 API 的说明。默认情况下,系统会使用 API 产品说明。您可以稍后更改显示说明,如修改显示标题和说明中所述。 要求开发者指定回调网址 如果您希望要求应用开发者指定回调网址,请启用此 API。您可以稍后添加或更新回调网址,如管理 API 的回调网址中所述。 API 文档 如需使用 OpenAPI 文档,请执行以下操作: - 选择 OpenAPI 文档 (OpenAPI document)。
- 点击选择文档。
- 执行以下步骤之一:
- 点击我的规范标签页,然后从规范存储区中选择一个规范。
- 点击上传文件标签页,然后上传文件。
- 点击从网址导入标签页,然后从网址导入规范。
- 点击选择。
如需使用 GraphQL 架构,请执行以下操作:
- 选择 GraphQL 架构。
- 点击选择文档。
- 导航到 GraphQL 架构,并选择它。
- 点击选择。
或者,您也可以选择无文档,并在添加 API 后添加文档,如管理文档的快照中所述。
API 可见性 如果您尚未注册受众群体管理功能的 Beta 版,请选择以下选项之一:
- 匿名用户:允许所有用户查看 API。
- 注册用户:仅允许已注册的用户查看 API。
如果您已注册受众群体管理功能的 Beta 版,请选择以下选项之一:
- 公开(对所有人可见):允许所有用户查看 API。
- 经过身份验证的用户:仅允许已注册的用户查看 API。
- 选定受众群体:选择您希望能够查看 API 的特定受众群体。
您以后可以管理受众群体公开范围,如管理门户中 API 的公开范围中所述。
显示图片 如需在 API 页面上显示 API 卡片的图片,请点击选择图片。在选择图片对话框中,选择一个现有图片、上传新图片或提供外部图片的网址,然后点击选择。预览 API 缩略图,然后点击选择。您以后可以按照管理 API 卡片的图片中的说明添加图片。使用外部网址指定图片时,该图片不会上传到您的素材资源;此外,图片能否在集成门户中加载取决于其可用性,而内容安全政策可能会阻止或限制该图片。 类别 添加将要标记 API 的类别,使应用开发者可在 API 页面上发现相关的 API。如需识别某个类别,请执行以下操作:
- 从下拉列表中选择类别。
- 输入新类别的名称,然后按 Enter 键即可添加新类别。新类别便会添加到“类别”页面,并且在添加或修改其他 API 时可用。
点击保存。
管理文档的快照
发布 API 后,您可以随时截取 OpenAPI 或 GraphQL 文档的新快照,以更新在门户上发布的 API 参考文档。
如需管理文档的快照,请执行以下操作:
- 访问 API 目录。
- 点击 API 标签页(如果尚未选择)。
- 点击要修改的 API 对应的行。
- 检查快照状态。如果该密钥版本过旧,则会显示以下消息:
- 点击 。
- 执行以下任务之一:
- 如需刷新过期的 OpenAPI 文档的快照,请点击刷新快照。
- 如需更改用于为 API 生成文档的文档,请在“API 文档”下点击选择文档,然后选择新文档。
- 点击保存。
API 参考文档通过文档呈现,并添加到“API 参考”页面。快照状态已更新 更改为当前版本:
在门户上发布或取消发布 API
如需在您的门户上发布或取消发布 API,请执行以下操作:
- 访问 API 目录。
- 点击 API 标签页(如果尚未选择)。
- 点击要修改的 API 对应的行。
- 点击 。
- 在“API 详细信息”下,选择或取消选择已发布(在目录中列出),以分别在您的门户上发布或取消发布 API。
- 点击保存。
管理门户中 API 的公开范围
通过为以下各项授予访问权限,管理门户中 API 的公开范围:
- 公开(对所有人可见)
- 经过身份验证的用户
- 选定的受众群体(如果您已注册受众群体管理功能的 Beta 版)
如需管理门户中 API 的公开范围,请执行以下操作:
- 访问 API 目录。
- 点击 API 标签页(如果尚未选择)。
- 点击要修改的 API 对应的行。
- 点击 。
- 在 API 公开范围下,选择以下选项之一:
选择公开范围设置。如果您已注册受众群体功能的 Beta 版,请选择以下选项之一:
- 公开(对所有人可见):允许所有用户查看页面。
- 经过身份验证的用户:只允许注册用户查看页面。
- 已选择的受众群体会选择您希望能够查看相应网页的特定受众群体。请参阅管理门户的受众群体。
- 匿名用户:允许所有用户查看页面。
- 已注册的用户:只允许注册用户查看页面。
点击提交。
管理 API 的回调网址
管理 API 的回调网址。请参阅回调网址简介。
如需管理 API 的回调网址,请执行以下操作:
- 访问 API 目录。
- 点击 API 标签页(如果尚未选择)。
- 点击要修改的 API 对应的行。
- 点击 。
- 在“API 详细信息”下,选择或取消选择已发布(在目录中列出),以分别在您的门户上发布或取消发布 API。
- 点击保存。
管理 API 卡片的图片
通过添加图片或更改当前图片,管理 API 页面上的 API 卡片中显示的图片。
如需管理 API 卡片的图片,请执行以下操作:
- 访问 API 目录。
- 点击 API 标签页(如果尚未选择)。
- 点击要修改的 API 对应的行。
- 点击 。
在“API 详细信息”下:
- 点击选择图片以指定图片;如果当前未选择任何图片,则上传图片。
- 点击更改图片以指定或上传其他图片。
- 点击图片中的 x 可将其移除。
指定图片时,请指定具有目录项所用外部网址的图片,或存储在门户中的图片文件的文件路径,例如
/files/book-tree.jpg
。指定外来图片的网址时,图片不会上传到您的资产;此外,在集成式门户中加载图片会受到其可用性的约束,而这可能会受内容安全政策的阻止或限制。点击保存。
使用类别标记 API
您可以通过以下方式之一使用类别标记 API:
- 如下所述,在修改 API 时管理要标记其 API 的类别。
- 在修改类别时管理针对类别标记的 API。
要在修改 API 时针对类别标记 API,请执行以下操作:
- 访问 API 目录。
- 点击 API 标签页(如果尚未选择)。
- 点击要修改的 API 对应的行。
- 点击 。
- 点击类别字段并执行以下某个步骤:
- 从下拉列表中选择类别。
- 输入新类别的名称,然后按 Enter 键即可添加新类别。新类别便会添加到“类别”页面,并且在添加或修改其他 API 时可用。
- 重复操作可将 API 标记为更多类别。
- 点击保存。
修改显示标题和说明
要修改显示标题和说明,请执行以下操作:
- 访问 API 目录。
- 点击 API 标签页(如果尚未选择)。
- 点击要修改的 API 对应的行。
- 点击 。
- 根据需要修改显示标题和显示说明字段。
- 点击保存。
从门户中移除 API
如需从您的门户中移除 API,请执行以下操作:
- 访问 API 目录。
- 选择 API(如果尚未选择)。
- 将光标置于列表中的 API 上以显示操作菜单。
- 点击 。
管理用于发现相关 API 的类别
使用类别标记 API,使应用开发者可在实时门户的 API 页面上发现相关 API。添加和管理类别,如以下部分所述。
浏览“类别”页面
要查看“类别”页,请按以下步骤操作:
- 选择发布 > 门户,然后选择您的门户。
- 在门户着陆页上点击 API 目录 (API catalog)。
或者,您可以在顶部导航栏的门户下拉菜单中选择 API 目录 (API catalog)。
- 点击类别标签。
API 目录中的“类别”标签页会显示已为您的门户定义的类别列表。
如上图突出显示,您可以通过 API 页面执行以下操作:
添加类别
您可以通过以下任一方式添加类别:
- 在向门户添加 API 时输入类别名称
- 手动添加类别,如下所述
新类别便会添加到“类别”页面,并且在添加或修改其他 API 时可用。
要手动添加类别,请执行以下操作:
- 访问“类别”页面。
- 点击 +。
- 输入新类别的名称。
- (可选)选择一个或多个要针对类别进行标记的 API。
- 点击创建。
修改类别
如需修改类别,请执行以下操作:
- 访问“类别”页面。
- 点击 。
- 修改类别的名称。
- 添加或移除 API 标记。
- 点击保存。
删除类别
如果删除类别,则该类别的所有 API 标记也将被删除。
要删除类别,请执行以下操作:
- 访问“类别”页面。
- 将光标置于您要修改的类别上方以显示操作菜单。
- 点击 。
- 修改类别的名称。
- 添加或移除 API。
- 点击保存。
排查已发布的 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 规范的行为。