您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档。 信息
借助 SmartDocs,您可以在 Drupal 7 开发者门户上记录 API,从而使 API 文档具有完全可交互性。借助交互式文档,门户用户可以:
- 了解您的 API
- 向您的 API 发送实时请求
- 查看从 API 返回的实时响应
通过创建有关 API 的交互式文档,门户用户能够轻松地学习、测试和评估您的 API。
Edge Management API 是一个 RESTful API,使您能够使用任何 HTTP 客户端访问 API 服务。Apigee 使用 SmartDocs 为 Edge Management API 创建交互式文档。请点击此处查看该 API 文档。
SmartDocs 门户示例
如需使用 SmartDocs,您必须拥有 Apigee Developer Services 门户。如需了解详情,请参阅创建开发者门户。
在开发者门户首页,点击顶部导航栏中的 API 以查看 API 文档页面。
该门户上记录了两个 API:Hello World 和 Pet Store Example。
Hello World API 是根据模拟目标 OpenAPI 规范 mocktarget.yaml
创建的。如需了解详情,请参阅 https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi。
Pet Store Example API 基于经典的 pet Store 演示创建。
探索 Hello World API:
- 点击 Hello World API。系统随即会显示 Hello World API 摘要页面:
- 点击查看 API 自我肯定话语。系统会显示此资源的 SmartDocs:
- 点击发送此请求。
- 查看返回的响应:
HTTP/1.1 200 OK Connection: keep-alive Content-Length: 18 Content-Type: text/html; charset=utf-8 Date: Tue, 21 Jun 2016 21:49:32 GMT ETag: W/"12-Jb9QP1bUxNSmZkxQGt5KLQ" X-Powered-By: Apigee <H2>I <3 APIs</H2>
- 点击 Request 标签页以查看请求,或点击 c网址 标签页查看对应的 c网址 调用。
如何使用 SmartDocs 编写 API 文档
SmartDocs 使用模型表示您的 API,其中模型包含有关您的 API 的所有信息。model门户会从模型中提取 API 相关信息,将门户上的文档页面呈现为 Drupal 节点,其中每个 Drupal 节点都对应于门户上的一个文档页面。
您可以按照以下常规步骤使用 SmartDocs:
- 在门户上配置 Drupal SmartDocs 模块。
- 创建 SmartDocs 模型。
- 从 WADL 文件、OpenAPI(以前称为 Swagger)规范或手动方式向模型添加 API。
- 将模型渲染为一组 Drupal 节点。每个 Drupal 节点都包含单个 API 的相关信息。例如,如果 API 中的某项资源同时支持 POST 和 PUT 请求,SmartDocs 将为 POST 和 PUT 创建单独的 Drupal 节点。
- 发布 Drupal 节点。发布之后,您的门户用户可以查看您的 API 并与之互动。
- 在发布之前或之后修改 Drupal 节点。您可以使用 Drupal 编辑器或者修改原始 WADL 文件或 OpenAPI 规范来修改 Drupal 节点。修改完 WADL 文件或 OpenAPI 规范后,请将其作为新修订版本重新导入模型中,然后渲染并发布您所做的更改。
- 启用 TLS。由于 SmartDocs 在向 API 发出请求时可以将身份验证凭据发送到后端,因此您应该在门户上启用 TLS,以确保这些凭据是安全的。在门户生产环境和测试环境中,Apigee 提供发出 https:// 请求所需的 TLS 证书。但是,在使用门户之前,您必须获取自己的 TLS 证书并启用 TLS。如需了解详情,请参阅在门户上使用 TLS。
关于 SmartDoc 模型和模板
在门户中创建模型时,模型实际上存储在 Edge 组织中,而非 Drupal 中。模型是一大块 JSON,具有内部名称(例如“my-smartdocs-api”),它定义了 API 的结构。另一方面,您的门户会以 HTML 形式呈现模型,并为模型提供修改界面。门户中的 API 更新会自动推送回源模型。
已存储在组织中 |
存储在 Drupal 中 |
---|---|
模型 |
模板 具有编辑功能的 Drupal 节点 |
假设您的组织中有多个门户(例如开发、阶段和生产门户)。在 Pantheon 中,您可以将门户从一个环境移至另一个环境。门户的每个实例都似乎包含自己的模型,但所有实例都引用了源模型。如果您在 dev 中修改 API,模型会更新,并且相应更改也会出现在生产环境中。同样,如果您在 dev 中删除模型,则源代码也会被删除,不再在生产环境中提供。
模板控制 SmartDocs 的外观和风格,这些模板(由 Handlebar 和 CSS 文件控制)存储在每个门户实例中。因此,从理论上讲,每个门户可以为每个模型使用唯一的模板。不过,渲染框架的便利性之一是,系统会自动为每个模型应用默认模板(Apigee 默认模板或您提供的模板)。
下图显示了模型和门户之间的关系。绿色箭头表示自动同步。
以下 c网址 命令会列出组织中的所有模型:
curl -v https://api.enterprise.apigee.com/v1/o/{your_org}/apimodels/ -u
edge_org_admin@example.com
配置 SmartDocs 模块
Apigee 以自定义 Drupal 模块的形式实现了 SmartDocs。请按照以下步骤配置 SmartDocs 模块。
要配置 SmartDocs 模块,请执行以下操作:
- 以拥有管理员或内容创建权限的用户身份登录门户。
- 在 Drupal 管理菜单中选择模块。系统会显示所有已安装的 Drupal 模块的列表。
- 启用 SmartDocs 模块。
- 保存配置。
-
在 Drupal 管理菜单中选择模块。
-
依次选择 SmartDocs -> 权限,并确保为“管理员”角色启用了“对 SmartDocs 模块执行管理任务”。
- 在 Drupal 管理菜单中,依次选择配置 > 开发门户。
- 将连接超时和请求超时设置为 16 秒。
- 保存配置。
- 配置网址设置:
- 从 Drupal 菜单中依次选择配置 > 搜索和元数据 > 网址别名 > 设置。
- 将别名长度上限和组件长度上限设置为 255。
- 展开标点。
- 对于左花括号 ({) 和右花括号 (}) 设置,请选择 No action (do not replace)。
- 点击 Save configuration(保存配置)。
- 如果您的开发者门户将在无法访问互联网的内部网络中公开,或者您的部分 API 位于专用网络上,请配置 SmartDocs API 代理网址,如下所示:
- 在 Drupal 管理菜单中,依次选择配置 > SmartDocs。
- 展开高级设置。
- 更新 SmartDocs 代理网址字段,如下所示:
<host>/smartdocs/v1/sendrequest
。
内嵌帮助应提供您环境所需的值。例如:
https://api-us-east-1-enterprise.apigee.com/smartdocs/v1/sendrequest
此字段默认为https://apiconsole-prod.apigee.net/smartdocs/v1/sendrequest
- 点击 Save configuration(保存配置)。
创建模型
模型包含有关 API 表示法的所有信息。您可以在门户上定义多个模型以支持不同的 API,也可以将所有 API 分组到单个模型中。
每个模型会指定唯一的内部名称,该名称还定义了生成的 Drupal 节点的基础网址。每个 Drupal 节点的网址都采用以下格式:
http://<drupalBasePath>/<internalName>/apis/<httpMethod>/<resourcePath>
其中:
- drupalBasePath:门户的基础网址。
- internalName:模型的内部名称。
- httpMethod:API 的 HTTP 方法,例如:get、put、post 或 delete。
- resourcePath:资源路径。
例如,如果您将内部名称指定为“mymodel”,则对于名为“/books”的资源发出 GET 请求,所生成的 Drupal 节点的网址如下:
http://prod-myco.devportal.apigee.com/mymodel/apis/get/books
创建模型
创建模型后,模型会作为 API 结构的来源存储在 Edge 组织中。如需了解详情,请参阅 SmartDoc 模型和模板简介。
- 以拥有管理员或内容创建权限的用户身份登录门户。
- 在 Drupal 管理菜单中,依次选择内容 > SmartDocs。
- 在页面顶部选择新建模型。
- 输入以下字段:
- 名称:将在该网站上显示的模型名称。
- 内部名称:输入名称时,系统会显示内部名称。模型的内部名称,在所有模型中必须是唯一的。 内部名称只能包含小写字母、数字和连字符,不得包含空格。选择修改即可修改此名称。
- 说明:模型的说明。
- 选择创建模型。
创建模型后,系统会将您重定向到模型的页面。然后,您可以使用“操作”下拉菜单 bx 执行以下操作:
- 导入描述 API 的 WADL 文件,或指定描述 API 的 OpenAPI 规范的网址。
- 向模型添加修订版本
- 修改模型设置,包括模型使用的样式表。
- 将模型导出到文件中。
- 删除模型。
向模型添加 API
您可以通过以下方式向模型添加 API:
- 导入包含 API 定义的 WADL 文件
- 导入 OpenAPI 规范(OpenAPI 2.0 或 1.2)
- 手动创建资源和方法
您还可以将 SmartDocs JSON 文件导入模型中。创建此文件通常采用以下方法:首先导出现有模型,修改该文件,然后导入更新。如需了解详情,请参阅下文的“导出和导入模型”。
视频:观看一小段视频,了解如何通过导入 OpenAPI 规范来向 SmartDocs 模型添加 API。
导入 WADL
成功创建模型后,请导入描述您的 API 的 WADL 文件。每次导入 WADL 文件时,您都会自动创建新的模型修订版本。
- 以拥有管理员或内容创建权限的用户身份登录门户。
- 在 Drupal 管理菜单中选择内容 > SmartDocs。
- 选择要更新的模型。
- 在操作下,选择导入。
- 在 SmartDocs 导入页面上的选择格式下拉列表中选择 WADL。
- 在上传类型下拉列表中,选择文件或网址。
- 如果您选择 File(文件),请找到相应的 WADL 文件。
- 如果您选择网址,请指定 WADL 文件的网址。
- 点击导入,将其导入模型。您现在可以渲染模型了。
- 您将被重定向到模型的信息页面,您现在可以渲染模型。
导入 OpenAPI 规范
成功创建模型后,您可以导入 OpenAPI(以前称为 Swagger)规范。Edge 支持 OpenAPI 版本 1.2 和 2.0。
OpenAPI 使用包含 JSON 对象的文件来描述 API。每次导入 OpenAPI 规范时,您都会自动创建模型的新修订版本。
要导入 OpenAPI 规范,请执行以下操作:
- 以拥有管理员或内容创建权限的用户身份登录门户。
- 在 Drupal 管理菜单中选择内容 > SmartDocs。
- 选择要更新的模型。
- 在操作下,选择导入。
- 在 SmartDocs 导入页面上的选择格式下拉列表中,选择 Swagger JSON 或 Swagger YAML。
- 在上传类型下拉列表中选择文件或网址(对于 OpenAPI 1.2,您必须选择 网址)。
- 如果选择文件,请浏览 OpenAPI 规范。
- 如果您选择 网址,请指定 OpenAPI 规范的网址。
- 点击导入,将其导入模型。
- 您将被重定向到模型的信息页面,您现在可以渲染模型。
手动创建资源和方法
如果您没有代表您的 API 的 WADL 文件或 OpenAPI 规范,可以手动将 API 添加到模型中。此外,如果您使用 WADL 文件或 OpenAPI 规范来创建模型,则可以在导入后按照此过程修改 API,包括添加新 API。
如需手动添加 API,请执行以下操作:
- 创建模型的新修订版本。
创建修订版本时,您可以指定模型中所有 API 的单个基本路径,这意味着模型中的所有 API 共享相同的基本路径。例如,将基本路径指定为:
https://myCompany.com/v1
当您向模型添加资源时,这些资源会扩展基本路径。 - 为模型定义一项或多项资源。资源路径与模型修订版本的基本路径相结合,以指定资源的完整网址。例如,如果您的资源定义了“/login”路径,则该资源的完整网址为:
https://myCompany.com/v1/login - 为每个资源定义一个或多个方法。方法指定可对资源调用的 HTTP 动词。例如,对于“/login”资源,您支持 POST 登录和 DELETE,退出登录。此资源不支持其他 HTTP 动词,例如 PUT 或 GET。
因此,请为资源定义两个方法,一个用于 POST,另一个用于 DELETE。
方法使用其父资源中的资源网址。因此,在 SmartDocs 中,具有相同网址的所有方法均在单个资源下定义。
作为一般的规则:
- 为您的 API 中的每个唯一基本路径创建不同的 SmartDocs 模型。
- 为 API 中的每个唯一资源定义不同的 SmartDocs 资源。
- 为资源支持的每个 HTTP 动词定义不同的 SmartDocs 方法。
创建新的模型修订版本
您只能将资源添加到模型的现有修订版本。如果模型已有修订版本,您可以添加资源。如果模型是新模型且没有修订版本,请创建新的修订版本。
如需为模型创建新的修订版本,请执行以下操作:
- 以拥有管理员或内容创建权限的用户身份登录门户。
- 在 Drupal 管理菜单中,选择 内容 > SmartDocs。
- 对于要更新的模型,请在操作下选择添加 修订版本。
- 在添加 API 修订版本页面上,输入以下信息:
- 显示名:修订版本在门户中显示的名称。
- 版本 ID:修订版本的简短标识符。
- 说明:对修订版本的说明。
- 基准网址:模型修订版中所有 API 的基础网址。模型可以为每个修订版本使用不同的基准网址。例如,您可以在基准网址中添加版本指示器。对于第一个模型修订版本,基准网址为:
https://myCompany.com/v1
对于下一个修订版本,基准网址可以是:
https://myCompany.com/v2
- 选择添加修订版本。您将被重定向到模型的修订版本页面。您现在可以在模型上定义资源。
定义资源
资源指定 API 的完整网址。定义资源时,您要指定资源路径,该路径会与模型修订版本中的基准网址相结合,以创建资源的完整网址。
如需定义资源,请执行以下操作:
- 以拥有管理员或内容创建权限的用户身份登录门户。
- 在 Drupal 管理菜单中,依次选择 内容 > SmartDocs。
- 对于要更新的模型,请在操作下选择 API 修订版本以查看模型的所有修订版本。
- 选择要修改的修订版本。
- 在修订版本页面上,从下拉菜单中选择添加资源。
- 在添加资源页面上,输入以下信息:
- 显示名:资源的名称。
- 路径:以“/”开头的资源路径。Path 的值将与模型修订版本的基准网址相结合,以创建资源的完整网址。
- 说明:对资源的说明。
- 参数:(可选)输入用于定义资源上每个参数的 JSON 对象。下面介绍了这些参数。
- 选择添加资源。您将被重定向到模型页面。您现在可以针对资源定义方法。
您可以选择向该资源添加参数,例如模板、查询和标头参数。在该资源上定义的任何方法都会继承所有资源参数。因此,如果您在资源上定义了查询参数,则添加到该资源的所有方法都必须支持该查询参数。
或者,您也可以在方法中定义参数。例如,POST 方法可能支持 DELETE 方法不支持的查询参数。因此,在定义某个方法时,请添加该方法特有的任何参数,如下文所述。
下图显示了 Apigee Approve or Revoke Developer App API 的现有 SmartDocs 页面,其中突出显示了每种类型的参数:
每个参数类型都由一个 JSON 对象定义:
类型 |
JSON 对象 |
备注 |
---|---|---|
模板 |
{ |
模板参数始终是必需的,因此请将 required 设置为 true,并省略 defaultValue 的值。 当用户将鼠标悬停在 SmartDocs 页面中的网址上时,description 值会显示在弹出式窗口中。 |
查询 |
{ |
必需的查询参数仍可指定 defaultValue,但通常不指定。 对于可选查询参数,请将 required 设置为 false,并将值指定为 defaultValue。 |
标题 |
{ |
请注意如何在说明中使用 HTML 标记。 |
模板参数定义资源路径中的变量。例如,您在资源上定义了两个模板参数。请注意参数数组中的每个参数定义是如何以英文逗号分隔的:
[ { "dataType": "string", "defaultValue": "", "description": "Mention the organization name.", "name": "org_name", "required": true, "type": "TEMPLATE" }, { "dataType": "string", "defaultValue": "", "description": "Mention the user email.", "name": "developer_email", "required": true, "type": "TEMPLATE" } ]
然后,您可以在资源路径定义中使用模板参数(括在“{}”中)。例如,将路径设置为:
/login/{org_name}/{developer_email}
在 SmartDocs API 页面中,用户必须编辑网址以指定网址的 org_name 和 developer_email 部分,才能提交请求。
定义方法
为每个资源定义一个或多个方法。方法定义指定了可对资源调用的 HTTP 动词。您可以为资源定义单个方法,也可以定义多个方法。
在定义方法时,请指定方法使用的任何参数,包括查询和标头参数。如需了解如何向方法添加参数,请参阅上文中的说明。
下图显示了 Apigee Create Developer API 的现有 SmartDocs 页面,其中突出显示了页面的每个区域(使用您在定义方法时设置的相应值):
下图显示了同一页面,但选择了“Request Body”的说明:
如需定义方法,请执行以下操作:
- 以拥有管理员或内容创建权限的用户身份登录门户。
- 在 Drupal 管理菜单中,选择 内容 > SmartDocs。
- 对于要更新的模型,请在操作下选择 API 修订版本以查看模型的所有修订版本。
- 选择要修改的修订版本。
- 在修订版本页面上,从其中一个资源下拉菜单中选择 Add Method(添加方法)。
- 在 Edit Method(修改方法)页面上,输入以下信息:
- 显示名:API 的名称,还会成为该 API 的 Drupal 页面的标题。
- 说明:描述此 API。
- 方法 Verb:HTTP 动词类型。
- 安全方案:为方法指定身份验证模式(如果有)。如需了解详情,请参阅配置 SmartDocs 身份验证类型。
- 内容类型:请求和响应的内容类型。如需了解如何配置不同的身份验证方法,请参阅下文。
- 参数:(可选)方法的任何查询或标头参数。如需了解详情,请参阅上文中的说明,了解如何向资源添加参数。
- 请求正文文档:(可选)描述请求正文。POST 和 PUT 方法接受请求正文。您可以使用此区域来对其进行描述。如果省略此值,则生成的 SmartDocs 页面中将省略请求正文下的说明链接。
- 请求正文示例:(可选)显示请求正文的示例,通常采用 JSON 对象或 XML 格式。对于 POST 和 PUT 动词,请求正文示例会作为每个请求的一部分进行传递。“SmartDocs”页面的用户在向 API 提交请求之前可以修改此示例。如果省略此值,则生成的 SmartDocs 页面中将省略请求正文下的值链接。
- 代码:与 API 相关联的代码的数组。SmartDocs 使用标记将类似的 API 分组在一起。例如,您可以将“统计数据”标记应用于所有与统计信息相关的 API。您可以将来自不同资源的 API 分组到一个标记下(如果它们都使用相同的标记)。
- 选择 Add Method(添加方法)。您将被重定向到模型页面。您现在可以渲染和发布您的方法了。
渲染模型
将 API 添加到模型后,您可以渲染该模型。渲染会将模型对 API 的说明转换为 Drupal 节点。渲染完成后,每个 API 都有一个 Drupal 节点,其中每个 Drupal 节点都对应一个 HTML 网页。
您可以选择一次渲染整个模型,也可以选择单个 API 进行渲染。
如需渲染模型,请执行以下操作:
- 以拥有管理员或内容创建权限的用户身份登录门户。
- 在 Drupal 管理菜单中,选择 内容 > SmartDocs。
- 对于要渲染的模型,选择“操作”下的 API 修订版本。
- 选择要渲染的修订版本。您只能通过模型的单个修订版本渲染节点。
- 选择要呈现的方法。
- 从 Update options 下拉列表中选择 Render Nodes。
- 点击更新。
- 系统会显示一个加载屏幕,供您查看渲染节点的进度。
节点渲染后,每个 API 的 Drupal 节点的 ID 会显示在模型的节点关联列下。点击节点关联列中的链接,查看呈现的节点。
您可以选择渲染和发布节点,以渲染并立即以 Drupal 节点的形式发布 API,而不是选择渲染节点。
发布节点
节点在发布之前不会向门户用户显示。您可以选择在渲染过程中发布节点。如果您选择不发布节点,则必须在渲染完成后手动发布节点。
如需发布节点,请执行以下操作:
- 以拥有管理员或内容创建权限的用户身份登录门户。
- 在 Drupal 管理菜单中,选择 内容 > SmartDocs。
- 对于要发布的模型,请选择“操作”下的 API 修订版本。
- 选择要发布的修订版本。您只能从模型的单个修订版本发布节点。
- 选择要发布的方法。
- 选择要发布的修订版本中的节点。
- 从更新 选项下拉列表中选择发布节点。
- 点击更新。
- 在节点关联列下选择节点 ID 以转到相应节点。
默认情况下,已发布 API 节点的 Drupal 网址采用以下格式:http://<drupalBasePath>/<drupalBasePath>/apis/<drupalBasePath>/<drupalBasePath>。如需控制网址的格式,请按以下步骤操作:
- 以拥有管理员或内容创建权限的用户身份登录门户。
- 在 Drupal 管理菜单中,依次选择配置 > 搜索和元数据 > 网址别名 > 模式。
- 在所有 SmartDocs 方法路径的模式下,指定您希望如何生成路径。
- 选择保存配置。
由于门户上有缓存,因此模型页面在发布后可能不会立即显示。如有必要,您可以通过以下步骤手动清除 SmartDocs HTML 缓存:
- 以拥有管理员或内容创建权限的用户身份登录门户。
- 在 Drupal 管理菜单中,依次选择配置 > SmartDocs。
- 点击重新构建 SmartDocs 模型缓存。
取消发布节点
您可以随时取消发布已发布的节点。取消发布节点会使其对门户用户不可见。
如需取消发布节点,请执行以下操作:
- 以拥有管理员或内容创建权限的用户身份登录门户。
- 在 Drupal 管理菜单中,选择 内容 > SmartDocs。
- 对于要取消发布的模型,选择“操作”下的 API 修订版本。
- 选择您要取消发布的节点的模型修订版本。
- 选择要取消发布的修订版本中的节点。
- 从更新 选项下拉列表中选择取消发布节点。
- 点击更新。
查看模型的修订版本
您可以通过将新的 WADL 文件或 OpenAPI 规范导入现有模型,或手动创建新的修订版本来创建新的模型修订版本。创建新修订版本后,您可以渲染和发布该修订版本,该修订版本将替换当前发布的 Drupal 节点。
您可以同时渲染和发布多个修订版本中的节点。这意味着,如果某个模型有五个修订版本,则可以从任何或所有修订版本发布节点。但是,在与另一个模型中的已发布节点相同的一个模型中发布 API,则会取消发布旧版 API,并将其替换为最近发布的 API 中的版本。
如需查看模型的修订版本,请执行以下操作:
- 以拥有管理员或内容创建权限的用户身份登录门户。
- 在 Drupal 管理菜单中,选择 内容 > 。
- 对于要更新的模型,选择“操作”下的 API 修订版本。
- 选择要查看的模型修订版本。
- 如上所述,渲染和发布节点。
修改节点
渲染节点后,您可以使用 Drupal 编辑器对其进行修改。例如,您可以修改 API 的 HTTP 动词和说明,或者向 API 添加新的查询或标头参数。您可以修改根据 WADL 文件或 OpenAPI 规范创建的节点,也可以修改手动创建的节点。
您还可以修改原始 WADL 文件或 OpenAPI 规范。修改完成后,请将 WADL 文件或 OpenAPI 规范作为新修订版本重新导入模型中,然后按照上述说明呈现并发布您所做的更改。
如需使用 Drupal 编辑器修改节点,请执行以下操作:
- 以拥有管理员或内容创建权限的用户身份登录门户。
- 浏览到与您要修改的 API 文档对应的 Drupal 节点。
- 选择修改以使用 Drupal 编辑器。
- 完成修改后,选择更新方法。
或者,您也可以在 SmartDocs 模型中修改节点:
- 以拥有管理员或内容创建权限的用户身份登录门户。
- 在 Drupal 管理菜单中,选择 内容 > 。
- 对于要更新的模型,选择“操作”下的 API 修订版本。
- 选择要发布的模型修订版本。
- 在操作下拉列表中选择要修改的方法的修改方法。
如需删除节点,请执行以下操作:
- 以拥有管理员或内容创建权限的用户身份登录门户。
- 在 Drupal 管理菜单中,选择 内容 > 。
- 对于要更新的模型,选择“操作”下的 API 修订版本。
- 选择要发布的模型修订版本。
- 从操作下拉菜单中选择删除方法。
注意:删除节点会同时从模型中移除相应 API。如果您只想取消发布 API 以使其对门户用户隐藏,但不想将其从模型中删除,则应按上文所述取消发布该节点。
该门户具有内置报告,该报告会显示由 SmartDocs 模型渲染的任何节点的相关信息,这些节点不再引用模型的有效方法。如需访问该报告,请选择 Drupal 菜单中的报告,然后选择名为 SmartDocs 节点状态的报告。
导出和导入模型
借助 SmartDocs,您可以将现有模型导出到文件中。例如,您可以定义生产环境和预演环境。然后,在预演环境中进行所有 SmartDocs 修改。准备好发布 API 后,您可以导出预演模型并将其导入生产模型。
导入模型会创建新的模型修订版本。SmartDocs 会尝试将模型中的现有 API 与导入的 API 进行匹配。如果 SmartDocs 检测到匹配项,则导入操作会更新与现有 API 对应的 Drupal 节点。如果 SmartDocs 未检测到匹配项,则导入操作会为 API 创建一个新的 Drupal 节点。
例如,您有一个 POST API 与 ID 为 91 的 Drupal 节点相对应。然后,您导入一个模型,SmartDocs 会在导入的模型中检测到与现有 POST API 匹配的 POST API。如果对 POST API 进行任何更新,之后便会更新 Drupal 节点 91。如果 SmartDocs 未检测到匹配项,则会创建一个具有新 ID 的新 Drupal 节点。
Drupal 会使用该 API 的以下特性进行匹配:
- internalName:内部模型名称。
- httpMethod:API 的 HTTP 方法,例如:GET、PUT、POST 或 DELETE。
- resourcePath:资源路径。
- query params:API 使用的任何查询参数。
如果导入的 API 的所有四个特性都与模型中的现有 API 匹配,则 SmartDocs 会更新现有的 Drupal 节点。
导出的模型由包含资源和方法条目的单个 JSON 对象表示。这意味着您可以修改导出的模型以修改资源或方法,然后重新导入模型。如果您修改了 JSON 对象,请勿修改以下字段:
- revisionNumber
- createdTime
- modifiedTime
- apiRevisionId
- resourceId
如需导出模型,请执行以下操作:
- 以拥有管理员或内容创建权限的用户身份登录门户。
- 在 Drupal 管理菜单中,选择 内容 > 。
- 针对要导出的模型,选择操作下的导出。
- 选择 SmartDocs JSON 作为导出文件类型。
- 点击导出。
- 系统会提示您将文件保存到磁盘或在编辑器中打开文件。
如需导入模型,请执行以下操作:
- 以拥有管理员或内容创建权限的用户身份登录门户。
- 在 Drupal 管理菜单中,选择 内容 > 。
- 对于要导入的模型,选择操作下的导入。
- 在选择格式下拉列表中选择 SmartDocs JSON。
-
在 “上传类型”中选择文件或网址:
- 如果您选择文件,请浏览到 JSON 文件。
- 如果您选择网址,请指定 SmartDocs JSON 文件的网址。
- 点击导入,将其导入模型。
- 您将被重定向到模型的信息页面,您现在可以渲染模型。请注意,导入操作会创建模型的新修订版本。
- 渲染并发布节点。
修改 SmartDocs 模板
SmartDocs 模板定义了您的 Drupal 节点在屏幕上的显示方式。每个 SmartDocs 模型都可以使用相同的默认模板,您也可以手动自定义用于各个模型的模板。
SmartDocs 模板包含一个编码为 Handlebars .hbr 文件的模板文件、CSS 文件和 JavaScript 文件。使用 Handlebars 时,大部分内容都是通过嵌入的手柄表达式(例如 &123;&123;body}}
)驱动的。文件顶部的注释中提供了现有 Handlebar 表达式的列表。如需了解如何使用 Handlebars 自定义模板,请参阅 http://handlebarsjs.com。
以下部分介绍了如何上传自定义 SmartDocs 模板文件,以供所有新模型使用,或者在将新 API 导入现有模型时使用、如何恢复原始的默认 SmartDocs 模板文件,以及如何修改单个模型的 SmartDocs 模板。
上传自定义 SmartDocs 模板文件
您可以上传自定义 SmartDocs 模板文件(格式为 Handlebars .hbr 文件),以便在创建新模型或将新 API 导入现有模型时用作默认模板。
如果您想使用默认的 SmartDocs 模板文件作为创建自定义 SmartDocs 模板文件的起点,则可以从以下位置下载副本:
profiles/apigee/modules/custom/devconnect/smartdocs/templates/smartdocs.hbr
要上传自定义 SmartDocs 模板文件,请执行以下操作:
- 以拥有管理员或内容创建权限的用户身份登录门户。
- 在 Drupal 管理菜单中,依次选择 配置 > SmartDocs。
- 展开页面的高级设置区域。
- 在“上传自定义方法模板”下,点击 Choose File(选择文件),然后找到 Handlebars .hbr 文件。
- 点击上传。
- 点击 Save configuration(保存配置)。
恢复默认的 SmartDocs 模板文件
您可以恢复默认的 SmartDocs 模板文件。恢复后,在创建新模型或将新 API 导入现有模型时,系统将使用默认的 SmartDocs 模板文件。
要恢复默认的 SmartDocs 模板文件,请执行以下操作:
- 以拥有管理员或内容创建权限的用户身份登录门户。
- 在 Drupal 管理菜单中,依次选择 配置 > SmartDocs。
- 展开页面的高级设置区域。
- 在“上传自定义方法模板”下,点击自定义 SmartDocs 模板文件旁边的移除。
- 点击 Save configuration(保存配置)。
修改单个模型的 SmartDocs 模板
您可以修改单个模型的模板。
如需修改单个模型的模板,请执行以下操作:
- 以拥有管理员或内容创建权限的用户身份登录门户。
- 在 Drupal 管理菜单中,选择 内容 > 。
- 对于要修改的模型,选择操作下的设置。
- 在“Method Template”(方法模板)区域,根据需要修改模板。
- 点击保存模板。
- 浏览到 Drupal 节点。您应该会在页面上看到模板更改。
配置 SmartDocs 身份验证类型
SmartDocs 中定义的 API 可以是开放式 API,这意味着无需身份验证凭据即可访问这些 API,也可以是安全的。安全的 API 要求您在调用 API 时传递凭据。
对于安全的 API,SmartDocs 支持以下类型的身份验证:
- 基本身份验证 - 以用户名和密码对的形式传递基本身份验证凭据。如果您未指定使用 OAuth 作为凭据类型,则 API 默认使用基本身份验证。
- OAuth 2.0 - 第三方服务提供商对用户的凭据进行身份验证,确保用户拥有 API 的授权,然后颁发访问令牌。当您向受保护的 API 发出 SmartDocs 请求时,SmartDocs 会构建该请求并将其发送给服务提供商。然后,服务提供商会验证令牌,确保其未过期。
- 自定义令牌 - 将令牌值作为标头或查询参数传递给每个请求。
对于每种身份验证类型,您可以创建一个安全机制来定义身份验证的特征。例如,对于自定义令牌身份验证,安全方案定义了令牌的传递方式(标头、查询参数、正文参数)以及令牌的名称。
安全方案与模型的特定修订版本相关联。因此,如果创建新的模型修订版本,则必须为该修订版本重新定义安全方案
在 WADL 文件中,您可以使用 <apigee:authentication> Apigee 标记指定 API 是否需要进行身份验证,如下所示:
<method id="statusespublic_timeline" name="GET" apigee:displayName="PublicTimeline"> ... <apigee:authentication required="true"/> </method>
如果 API 是开放的,请将 required 属性设为 false。
请注意,您无法在 WADL 文件中指定身份验证类型。为此,您可以在 Drupal 中修改节点。如需详细了解 WADL 文件,请参阅 WADL 参考文档。
在 Drupal 的 API 页面上,SmartDocs 添加了以下按钮,以允许用户指定其基本身份验证凭据:
如果您修改节点以将身份验证类型设置为 OAuth,则 SmartDocs 会将以下按钮添加到页面中:
对于自定义令牌,SmartDocs 添加了以下内容:
配置基本身份验证
如果您的 API 使用基本身份验证,则只需在用于创建模型的 WADL 文件中指定 <apigee:authentication> 标记。
如需将基本身份验证应用于从 WADL 文件以外的来源创建的方法,请执行以下操作:
- 以拥有管理员或内容创建权限的用户身份登录门户。
- 选择 内容 > “Drupal 管理”菜单中的 SmartDocs。
- 对于所需的模型,选择“操作”下的 API 修订版本。
- 对于要修改的模型修订版本,选择操作下的安全设置。
- 选择添加安全方案。
- 指定安全方案的名称。
- 选择基本作为类型。
- 选择提交。
- 对于模型中的每个方法,请修改方法,将其安全方案设置为您的基本方案。
- 选择 内容 > “Drupal 管理”菜单中的 SmartDocs。
- 对于所需的模型,选择“操作”下的 API 修订版本。
- 对于要修改的模型修订版本,选择操作下的修订版本详情。
- 为要修改的 API 选择修改方法。
- 选择 API 的安全方案。
- 保存该 API。
配置 OAuth 2.0 身份验证
您可以在 SmartDocs 中将模型配置为使用 OAuth 2.0,而不是默认使用基本身份验证。您可以在两个位置配置 OAuth:
- 在模型的每个修订版本的安全设置下,为该修订版本创建一个安全方案。
- 在模型的设置下,为模型的所有修订版本指定客户端 ID 和客户端密钥。
如需启用 OAuth,请执行以下操作:
- 以拥有管理员或内容创建权限的用户身份登录门户。
- 选择 内容 > “Drupal 管理”菜单中的 SmartDocs。
- 对于所需的模型,选择“操作”下的 API 修订版本。
- 对于要修改的模型修订版本,选择操作下的安全设置。
- 选择添加安全方案。
- 指定安全方案的名称。
- 选择 OAuth 2.0 作为类型。
- 设置授权类型。
- 在授权网址字段中输入值。授权网址用于获取访问令牌。
- 将 Authorization Verb(授权动词)设置为 GET 或 POST。
- 输入 Access Token 网址(访问令牌网址)。访问令牌网址用于将请求令牌交换为访问令牌。
- 输入 Access Token 参数名称。
- 使用 In 指定如何传递令牌:Header、Query 或 Body。
- 设置 OAuth 范围。
- 选择提交。
- 选择 内容 > “Drupal 管理”菜单中的 SmartDocs。
- 对于模型,请在操作下拉列表中选择设置。
- 在客户端 ID 和客户端密钥中输入值。
- 选择保存模板身份验证设置。
- 对于模型中的每个方法,请修改方法,将其安全方案设置为您的 OAuth 安全方案。
- 选择 内容 > “Drupal 管理”菜单中的 SmartDocs。
- 对于所需的模型,选择“操作”下的 API 修订版本。
- 对于要修改的模型修订版本,选择操作下的修订版本详情。
- 为要修改的 API 选择修改方法。
- 选择 API 的安全方案。
- 保存该 API。
配置自定义令牌身份验证
您可以将模型配置为使用自定义令牌身份验证。
如需启用自定义令牌,请按以下步骤操作:
- 以拥有管理员或内容创建权限的用户身份登录门户。
- 选择 内容 > “Drupal 管理”菜单中的 SmartDocs。
- 对于所需的模型,选择“操作”下的 API 修订版本。
- 对于要修改的模型修订版本,选择操作下的安全设置。
- 选择添加安全方案。
- 指定安全方案的名称。
- 选择 Apikey 作为类型。
- 设置包含相应令牌的 Param Name。
- 使用 In 指定如何传递令牌:Header、Query 或 Body。
- 选择提交。
- 对于模型中的每个方法,请修改方法,将其安全方案设置为您的令牌方案。
- 选择 内容 > “Drupal 管理”菜单中的 SmartDocs。
- 对于所需的模型,选择“操作”下的 API 修订版本。
- 对于要修改的模型修订版本,选择操作下的修订版本详情。
- 为要修改的 API 选择修改方法。
- 选择 API 的安全方案。
- 保存该 API。
删除模型
当您删除模型(Drupal 中的“操作”字段中的内容 > SmartDocs 和删除)后,该模型会从 Edge 组织中删除。这意味着,如果其他门户正在引用该模型,则该模型将不再可用。如需了解详情,请参阅 SmartDoc 模型和模板简介。