使用 SmartDocs 记录 API

您正在查看的是 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:

  1. 点击 Hello World API。系统随即会显示 Hello World API 摘要页面:
  2. 点击查看 API 自我肯定话语。系统会显示此资源的 SmartDocs:
  3. 点击发送此请求
  4. 查看返回的响应:
    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>
    
  5. 点击 Request 标签页以查看请求,或点击 c网址 标签页查看对应的 c网址 调用。

如何使用 SmartDocs 编写 API 文档

SmartDocs 使用模型表示您的 API,其中模型包含有关您的 API 的所有信息。model门户会从模型中提取 API 相关信息,将门户上的文档页面呈现为 Drupal 节点,其中每个 Drupal 节点都对应于门户上的一个文档页面。

您可以按照以下常规步骤使用 SmartDocs:

  1. 在门户上配置 Drupal SmartDocs 模块。
  2. 创建 SmartDocs 模型。
  3. 从 WADL 文件、OpenAPI(以前称为 Swagger)规范或手动方式向模型添加 API。
  4. 将模型渲染为一组 Drupal 节点。每个 Drupal 节点都包含单个 API 的相关信息。例如,如果 API 中的某项资源同时支持 POST 和 PUT 请求,SmartDocs 将为 POST 和 PUT 创建单独的 Drupal 节点。
  5. 发布 Drupal 节点。发布之后,您的门户用户可以查看您的 API 并与之互动。
  6. 在发布之前或之后修改 Drupal 节点。您可以使用 Drupal 编辑器或者修改原始 WADL 文件或 OpenAPI 规范来修改 Drupal 节点。修改完 WADL 文件或 OpenAPI 规范后,请将其作为新修订版本重新导入模型中,然后渲染并发布您所做的更改。
  7. 启用 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 模块,请执行以下操作

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 在 Drupal 管理菜单中选择模块。系统会显示所有已安装的 Drupal 模块的列表。
  3. 启用 SmartDocs 模块。
  4. 保存配置。
  5. 在 Drupal 管理菜单中选择模块
  6. 依次选择 SmartDocs -> 权限,并确保为“管理员”角色启用了“对 SmartDocs 模块执行管理任务”。
  7. 在 Drupal 管理菜单中,依次选择配置 > 开发门户
  8. 连接超时请求超时设置为 16 秒。
  9. 保存配置。
  10. 配置网址设置:
    1. 从 Drupal 菜单中依次选择配置 > 搜索和元数据 > 网址别名 > 设置
    2. 别名长度上限组件长度上限设置为 255
    3. 展开标点
    4. 对于左花括号 ({)右花括号 (}) 设置,请选择 No action (do not replace)
    5. 点击 Save configuration(保存配置)。
  11. 如果您的开发者门户将在无法访问互联网的内部网络中公开,或者您的部分 API 位于专用网络上,请配置 SmartDocs API 代理网址,如下所示:
    1. 在 Drupal 管理菜单中,依次选择配置 > SmartDocs
    2. 展开高级设置
    3. 更新 SmartDocs 代理网址字段,如下所示:<host>/smartdocs/v1/sendrequest
      内嵌帮助应提供您环境所需的值。例如:
      https://api-us-east-1-enterprise.apigee.com/smartdocs/v1/sendrequest

      此字段默认为 https://apiconsole-prod.apigee.net/smartdocs/v1/sendrequest
    4. 点击 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 模型和模板简介

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 在 Drupal 管理菜单中,依次选择内容 > SmartDocs
  3. 在页面顶部选择新建模型
  4. 输入以下字段:
    • 名称:将在该网站上显示的模型名称。
    • 内部名称:输入名称时,系统会显示内部名称。模型的内部名称,在所有模型中必须是唯一的。 内部名称只能包含小写字母、数字和连字符,不得包含空格。选择修改即可修改此名称。
    • 说明:模型的说明。
  5. 选择创建模型

创建模型后,系统会将您重定向到模型的页面。然后,您可以使用“操作”下拉菜单 bx 执行以下操作:

  • 导入描述 API 的 WADL 文件,或指定描述 API 的 OpenAPI 规范的网址。
  • 向模型添加修订版本
  • 修改模型设置,包括模型使用的样式表。
  • 将模型导出到文件中。
  • 删除模型。

向模型添加 API

您可以通过以下方式向模型添加 API:

  • 导入包含 API 定义的 WADL 文件
  • 导入 OpenAPI 规范(OpenAPI 2.0 或 1.2)
  • 手动创建资源和方法

您还可以将 SmartDocs JSON 文件导入模型中。创建此文件通常采用以下方法:首先导出现有模型,修改该文件,然后导入更新。如需了解详情,请参阅下文的“导出和导入模型”。

视频:观看一小段视频,了解如何通过导入 OpenAPI 规范来向 SmartDocs 模型添加 API。

导入 WADL

成功创建模型后,请导入描述您的 API 的 WADL 文件。每次导入 WADL 文件时,您都会自动创建新的模型修订版本。

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 在 Drupal 管理菜单中选择内容 > SmartDocs
  3. 选择要更新的模型。
  4. 操作下,选择导入
  5. 在 SmartDocs 导入页面上的选择格式下拉列表中选择 WADL
  6. 上传类型下拉列表中,选择文件网址
    1. 如果您选择 File(文件),请找到相应的 WADL 文件。
    2. 如果您选择网址,请指定 WADL 文件的网址。
  7. 点击导入,将其导入模型。您现在可以渲染模型了。
  8. 您将被重定向到模型的信息页面,您现在可以渲染模型。

导入 OpenAPI 规范

成功创建模型后,您可以导入 OpenAPI(以前称为 Swagger)规范。Edge 支持 OpenAPI 版本 1.2 和 2.0。

OpenAPI 使用包含 JSON 对象的文件来描述 API。每次导入 OpenAPI 规范时,您都会自动创建模型的新修订版本。

要导入 OpenAPI 规范,请执行以下操作:

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 在 Drupal 管理菜单中选择内容 > SmartDocs
  3. 选择要更新的模型。
  4. 操作下,选择导入
  5. 在 SmartDocs 导入页面上的选择格式下拉列表中,选择 Swagger JSONSwagger YAML
  6. 上传类型下拉列表中选择文件网址(对于 OpenAPI 1.2,您必须选择 网址)。
    1. 如果选择文件,请浏览 OpenAPI 规范。
    2. 如果您选择 网址,请指定 OpenAPI 规范的网址。
  7. 点击导入,将其导入模型。
  8. 您将被重定向到模型的信息页面,您现在可以渲染模型。

手动创建资源和方法

如果您没有代表您的 API 的 WADL 文件或 OpenAPI 规范,可以手动将 API 添加到模型中。此外,如果您使用 WADL 文件或 OpenAPI 规范来创建模型,则可以在导入后按照此过程修改 API,包括添加新 API。

如需手动添加 API,请执行以下操作

  1. 创建模型的新修订版本。

    创建修订版本时,您可以指定模型中所有 API 的单个基本路径,这意味着模型中的所有 API 共享相同的基本路径。例如,将基本路径指定为:

    https://myCompany.com/v1

    当您向模型添加资源时,这些资源会扩展基本路径。
  2. 为模型定义一项或多项资源。资源路径与模型修订版本的基本路径相结合,以指定资源的完整网址。例如,如果您的资源定义了“/login”路径,则该资源的完整网址为:

    https://myCompany.com/v1/login
  3. 为每个资源定义一个或多个方法。方法指定可对资源调用的 HTTP 动词。例如,对于“/login”资源,您支持 POST 登录和 DELETE,退出登录。此资源不支持其他 HTTP 动词,例如 PUT 或 GET。 因此,请为资源定义两个方法,一个用于 POST,另一个用于 DELETE。

    方法使用其父资源中的资源网址。因此,在 SmartDocs 中,具有相同网址的所有方法均在单个资源下定义。

作为一般的规则:

  • 为您的 API 中的每个唯一基本路径创建不同的 SmartDocs 模型。
  • 为 API 中的每个唯一资源定义不同的 SmartDocs 资源。
  • 为资源支持的每个 HTTP 动词定义不同的 SmartDocs 方法。

创建新的模型修订版本

您只能将资源添加到模型的现有修订版本。如果模型已有修订版本,您可以添加资源。如果模型是新模型且没有修订版本,请创建新的修订版本。

如需为模型创建新的修订版本,请执行以下操作

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 在 Drupal 管理菜单中,选择 内容 > SmartDocs
  3. 对于要更新的模型,请在操作下选择添加 修订版本
  4. 添加 API 修订版本页面上,输入以下信息:
    • 显示名:修订版本在门户中显示的名称。
    • 版本 ID:修订版本的简短标识符。
    • 说明:对修订版本的说明。
    • 基准网址:模型修订版中所有 API 的基础网址。模型可以为每个修订版本使用不同的基准网址。例如,您可以在基准网址中添加版本指示器。对于第一个模型修订版本,基准网址为:
      https://myCompany.com/v1
      对于下一个修订版本,基准网址可以是:
      https://myCompany.com/v2
  5. 选择添加修订版本。您将被重定向到模型的修订版本页面。您现在可以在模型上定义资源。

定义资源

资源指定 API 的完整网址。定义资源时,您要指定资源路径,该路径会与模型修订版本中的基准网址相结合,以创建资源的完整网址。

如需定义资源,请执行以下操作

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 在 Drupal 管理菜单中,依次选择 内容 > SmartDocs
  3. 对于要更新的模型,请在操作下选择 API 修订版本以查看模型的所有修订版本。
  4. 选择要修改的修订版本。
  5. 在修订版本页面上,从下拉菜单中选择添加资源
  6. 添加资源页面上,输入以下信息:
    • 显示名:资源的名称。
    • 路径:以“/”开头的资源路径。Path 的值将与模型修订版本的基准网址相结合,以创建资源的完整网址。
    • 说明:对资源的说明。
    • 参数:(可选)输入用于定义资源上每个参数的 JSON 对象。下面介绍了这些参数。
  7. 选择添加资源。您将被重定向到模型页面。您现在可以针对资源定义方法。

您可以选择向该资源添加参数,例如模板、查询和标头参数。在该资源上定义的任何方法都会继承所有资源参数。因此,如果您在资源上定义了查询参数,则添加到该资源的所有方法都必须支持该查询参数。

或者,您也可以在方法中定义参数。例如,POST 方法可能支持 DELETE 方法不支持的查询参数。因此,在定义某个方法时,请添加该方法特有的任何参数,如下文所述。

下图显示了 Apigee Approve or Revoke Developer App API 的现有 SmartDocs 页面,其中突出显示了每种类型的参数:

每个参数类型都由一个 JSON 对象定义:

类型

JSON 对象

备注

模板

{
"dataType": "string",
"defaultValue": "",
"description": "组织名称。",
"name": "org_name",
"required": true,
"type": "模板"
}

模板参数始终是必需的,因此请将 required 设置为 true,并省略 defaultValue 的值。

当用户将鼠标悬停在 SmartDocs 页面中的网址上时,description 值会显示在弹出式窗口中。

查询

{
"dataType": "string",
"defaultValue": "",
"description": "位置。",
"name": "w",
"required": true,
"type": "QUERY"
}

必需的查询参数仍可指定 defaultValue,但通常不指定。

对于可选查询参数,请将 required 设置为 false,并将值指定为 defaultValue

标题

{
"dataType": "string",
"defaultValue": "application/json",
"description": "指定为 <code>application/json</code>。",
"name": "Content-Type",
"required": true,
"type": "标头"
}

请注意如何在说明中使用 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_namedeveloper_email 部分,才能提交请求。

定义方法

为每个资源定义一个或多个方法。方法定义指定了可对资源调用的 HTTP 动词。您可以为资源定义单个方法,也可以定义多个方法。

在定义方法时,请指定方法使用的任何参数,包括查询和标头参数。如需了解如何向方法添加参数,请参阅上文中的说明。

下图显示了 Apigee Create Developer API 的现有 SmartDocs 页面,其中突出显示了页面的每个区域(使用您在定义方法时设置的相应值):

下图显示了同一页面,但选择了“Request Body”的说明:

如需定义方法,请执行以下操作

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 在 Drupal 管理菜单中,选择 内容 > SmartDocs
  3. 对于要更新的模型,请在操作下选择 API 修订版本以查看模型的所有修订版本。
  4. 选择要修改的修订版本。
  5. 在修订版本页面上,从其中一个资源下拉菜单中选择 Add Method(添加方法)。
  6. Edit Method(修改方法)页面上,输入以下信息:
    • 显示名:API 的名称,还会成为该 API 的 Drupal 页面的标题。
    • 说明:描述此 API。
    • 方法 Verb:HTTP 动词类型。
    • 安全方案:为方法指定身份验证模式(如果有)。如需了解详情,请参阅配置 SmartDocs 身份验证类型
    • 内容类型:请求和响应的内容类型。如需了解如何配置不同的身份验证方法,请参阅下文。
    • 参数:(可选)方法的任何查询或标头参数。如需了解详情,请参阅上文中的说明,了解如何向资源添加参数。
    • 请求正文文档:(可选)描述请求正文。POST 和 PUT 方法接受请求正文。您可以使用此区域来对其进行描述。如果省略此值,则生成的 SmartDocs 页面中将省略请求正文下的说明链接。
    • 请求正文示例:(可选)显示请求正文的示例,通常采用 JSON 对象或 XML 格式。对于 POST 和 PUT 动词,请求正文示例会作为每个请求的一部分进行传递。“SmartDocs”页面的用户在向 API 提交请求之前可以修改此示例。如果省略此值,则生成的 SmartDocs 页面中将省略请求正文下的链接。
    • 代码:与 API 相关联的代码的数组。SmartDocs 使用标记将类似的 API 分组在一起。例如,您可以将“统计数据”标记应用于所有与统计信息相关的 API。您可以将来自不同资源的 API 分组到一个标记下(如果它们都使用相同的标记)。
  7. 选择 Add Method(添加方法)。您将被重定向到模型页面。您现在可以渲染和发布您的方法了。

渲染模型

将 API 添加到模型后,您可以渲染该模型。渲染会将模型对 API 的说明转换为 Drupal 节点。渲染完成后,每个 API 都有一个 Drupal 节点,其中每个 Drupal 节点都对应一个 HTML 网页。

您可以选择一次渲染整个模型,也可以选择单个 API 进行渲染。

如需渲染模型,请执行以下操作

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 在 Drupal 管理菜单中,选择 内容 > SmartDocs
  3. 对于要渲染的模型,选择“操作”下的 API 修订版本
  4. 选择要渲染的修订版本。您只能通过模型的单个修订版本渲染节点。
  5. 选择要呈现的方法。
  6. Update options 下拉列表中选择 Render Nodes
  7. 点击更新
  8. 系统会显示一个加载屏幕,供您查看渲染节点的进度。
    节点渲染后,每个 API 的 Drupal 节点的 ID 会显示在模型的节点关联列下。点击节点关联列中的链接,查看呈现的节点。

您可以选择渲染和发布节点,以渲染并立即以 Drupal 节点的形式发布 API,而不是选择渲染节点

发布节点

节点在发布之前不会向门户用户显示。您可以选择在渲染过程中发布节点。如果您选择不发布节点,则必须在渲染完成后手动发布节点。

如需发布节点,请执行以下操作

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 在 Drupal 管理菜单中,选择 内容 > SmartDocs
  3. 对于要发布的模型,请选择“操作”下的 API 修订版本
  4. 选择要发布的修订版本。您只能从模型的单个修订版本发布节点。
  5. 选择要发布的方法。
  6. 选择要发布的修订版本中的节点。
  7. 更新 选项下拉列表中选择发布节点
  8. 点击更新
  9. 节点关联列下选择节点 ID 以转到相应节点。

默认情况下,已发布 API 节点的 Drupal 网址采用以下格式:http://<drupalBasePath>/<drupalBasePath>/apis/<drupalBasePath>/<drupalBasePath>。如需控制网址的格式,请按以下步骤操作:

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 在 Drupal 管理菜单中,依次选择配置 > 搜索和元数据 > 网址别名 > 模式
  3. 所有 SmartDocs 方法路径的模式下,指定您希望如何生成路径。
  4. 选择保存配置

由于门户上有缓存,因此模型页面在发布后可能不会立即显示。如有必要,您可以通过以下步骤手动清除 SmartDocs HTML 缓存:

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 在 Drupal 管理菜单中,依次选择配置 > SmartDocs
  3. 点击重新构建 SmartDocs 模型缓存

取消发布节点

您可以随时取消发布已发布的节点。取消发布节点会使其对门户用户不可见。

如需取消发布节点,请执行以下操作

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 在 Drupal 管理菜单中,选择 内容 > SmartDocs
  3. 对于要取消发布的模型,选择“操作”下的 API 修订版本
  4. 选择您要取消发布的节点的模型修订版本。
  5. 选择要取消发布的修订版本中的节点。
  6. 更新 选项下拉列表中选择取消发布节点。
  7. 点击更新

查看模型的修订版本

您可以通过将新的 WADL 文件或 OpenAPI 规范导入现有模型,或手动创建新的修订版本来创建新的模型修订版本。创建新修订版本后,您可以渲染和发布该修订版本,该修订版本将替换当前发布的 Drupal 节点。

您可以同时渲染和发布多个修订版本中的节点。这意味着,如果某个模型有五个修订版本,则可以从任何或所有修订版本发布节点。但是,在与另一个模型中的已发布节点相同的一个模型中发布 API,则会取消发布旧版 API,并将其替换为最近发布的 API 中的版本。

如需查看模型的修订版本,请执行以下操作:

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 在 Drupal 管理菜单中,选择 内容 >
  3. 对于要更新的模型,选择“操作”下的 API 修订版本
  4. 选择要查看的模型修订版本。
  5. 如上所述,渲染和发布节点。

修改节点

渲染节点后,您可以使用 Drupal 编辑器对其进行修改。例如,您可以修改 API 的 HTTP 动词和说明,或者向 API 添加新的查询或标头参数。您可以修改根据 WADL 文件或 OpenAPI 规范创建的节点,也可以修改手动创建的节点。

您还可以修改原始 WADL 文件或 OpenAPI 规范。修改完成后,请将 WADL 文件或 OpenAPI 规范作为新修订版本重新导入模型中,然后按照上述说明呈现并发布您所做的更改。

如需使用 Drupal 编辑器修改节点,请执行以下操作

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 浏览到与您要修改的 API 文档对应的 Drupal 节点。
  3. 选择修改以使用 Drupal 编辑器。
  4. 完成修改后,选择更新方法

或者,您也可以在 SmartDocs 模型中修改节点:

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 在 Drupal 管理菜单中,选择 内容 >
  3. 对于要更新的模型,选择“操作”下的 API 修订版本
  4. 选择要发布的模型修订版本。
  5. 操作下拉列表中选择要修改的方法的修改方法

如需删除节点,请执行以下操作

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 在 Drupal 管理菜单中,选择 内容 >
  3. 对于要更新的模型,选择“操作”下的 API 修订版本
  4. 选择要发布的模型修订版本。
  5. 操作下拉菜单中选择删除方法
    注意:删除节点会同时从模型中移除相应 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

如需导出模型,请执行以下操作

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 在 Drupal 管理菜单中,选择 内容 >
  3. 针对要导出的模型,选择操作下的导出
  4. 选择 SmartDocs JSON 作为导出文件类型。
  5. 点击导出
  6. 系统会提示您将文件保存到磁盘或在编辑器中打开文件。

如需导入模型,请执行以下操作

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 在 Drupal 管理菜单中,选择 内容 >
  3. 对于要导入的模型,选择操作下的导入
  4. 选择格式下拉列表中选择 SmartDocs JSON
  5. “上传类型”中选择文件网址
    1. 如果您选择文件,请浏览到 JSON 文件。
    2. 如果您选择网址,请指定 SmartDocs JSON 文件的网址。
  6. 点击导入,将其导入模型。
  7. 您将被重定向到模型的信息页面,您现在可以渲染模型。请注意,导入操作会创建模型的新修订版本。
  8. 渲染并发布节点。

修改 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 模板文件,请执行以下操作:

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 在 Drupal 管理菜单中,依次选择 配置 > SmartDocs
  3. 展开页面的高级设置区域。
  4. 在“上传自定义方法模板”下,点击 Choose File(选择文件),然后找到 Handlebars .hbr 文件。
  5. 点击上传
  6. 点击 Save configuration(保存配置)。

恢复默认的 SmartDocs 模板文件

您可以恢复默认的 SmartDocs 模板文件。恢复后,在创建新模型或将新 API 导入现有模型时,系统将使用默认的 SmartDocs 模板文件。

要恢复默认的 SmartDocs 模板文件,请执行以下操作:

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 在 Drupal 管理菜单中,依次选择 配置 > SmartDocs
  3. 展开页面的高级设置区域。
  4. 在“上传自定义方法模板”下,点击自定义 SmartDocs 模板文件旁边的移除
  5. 点击 Save configuration(保存配置)。

修改单个模型的 SmartDocs 模板

您可以修改单个模型的模板。

如需修改单个模型的模板,请执行以下操作:

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 在 Drupal 管理菜单中,选择 内容 >
  3. 对于要修改的模型,选择操作下的设置
  4. 在“Method Template”(方法模板)区域,根据需要修改模板。
  5. 点击保存模板
  6. 浏览到 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 文件以外的来源创建的方法,请执行以下操作:

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 选择 内容 > “Drupal 管理”菜单中的 SmartDocs。
  3. 对于所需的模型,选择“操作”下的 API 修订版本
  4. 对于要修改的模型修订版本,选择操作下的安全设置
  5. 选择添加安全方案
  6. 指定安全方案的名称
  7. 选择基本作为类型
  8. 选择提交
  9. 对于模型中的每个方法,请修改方法,将其安全方案设置为您的基本方案。
    1. 选择 内容 > “Drupal 管理”菜单中的 SmartDocs。
    2. 对于所需的模型,选择“操作”下的 API 修订版本
    3. 对于要修改的模型修订版本,选择操作下的修订版本详情
    4. 为要修改的 API 选择修改方法
    5. 选择 API 的安全方案
    6. 保存该 API。

配置 OAuth 2.0 身份验证

您可以在 SmartDocs 中将模型配置为使用 OAuth 2.0,而不是默认使用基本身份验证。您可以在两个位置配置 OAuth:

  1. 在模型的每个修订版本的安全设置下,为该修订版本创建一个安全方案。
  2. 在模型的设置下,为模型的所有修订版本指定客户端 ID 和客户端密钥。

如需启用 OAuth,请执行以下操作

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 选择 内容 > “Drupal 管理”菜单中的 SmartDocs。
  3. 对于所需的模型,选择“操作”下的 API 修订版本
  4. 对于要修改的模型修订版本,选择操作下的安全设置
  5. 选择添加安全方案
  6. 指定安全方案的名称
  7. 选择 OAuth 2.0 作为类型
  8. 设置授权类型
  9. 授权网址字段中输入值。授权网址用于获取访问令牌。
  10. Authorization Verb(授权动词)设置为 GET 或 POST。
  11. 输入 Access Token 网址(访问令牌网址)。访问令牌网址用于将请求令牌交换为访问令牌。
  12. 输入 Access Token 参数名称
  13. 使用 In 指定如何传递令牌:HeaderQueryBody
  14. 设置 OAuth 范围
  15. 选择提交
  16. 选择 内容 > “Drupal 管理”菜单中的 SmartDocs。
  17. 对于模型,请在操作下拉列表中选择设置
  18. 客户端 ID客户端密钥中输入值。
  19. 选择保存模板身份验证设置
  20. 对于模型中的每个方法,请修改方法,将其安全方案设置为您的 OAuth 安全方案。
    1. 选择 内容 > “Drupal 管理”菜单中的 SmartDocs。
    2. 对于所需的模型,选择“操作”下的 API 修订版本
    3. 对于要修改的模型修订版本,选择操作下的修订版本详情
    4. 为要修改的 API 选择修改方法
    5. 选择 API 的安全方案
    6. 保存该 API。

配置自定义令牌身份验证

您可以将模型配置为使用自定义令牌身份验证。

如需启用自定义令牌,请按以下步骤操作

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 选择 内容 > “Drupal 管理”菜单中的 SmartDocs。
  3. 对于所需的模型,选择“操作”下的 API 修订版本
  4. 对于要修改的模型修订版本,选择操作下的安全设置
  5. 选择添加安全方案
  6. 指定安全方案的名称
  7. 选择 Apikey 作为类型
  8. 设置包含相应令牌的 Param Name
  9. 使用 In 指定如何传递令牌:HeaderQueryBody
  10. 选择提交
  11. 对于模型中的每个方法,请修改方法,将其安全方案设置为您的令牌方案。
    1. 选择 内容 > “Drupal 管理”菜单中的 SmartDocs。
    2. 对于所需的模型,选择“操作”下的 API 修订版本
    3. 对于要修改的模型修订版本,选择操作下的修订版本详情
    4. 为要修改的 API 选择修改方法
    5. 选择 API 的安全方案
    6. 保存该 API。

删除模型

当您删除模型(Drupal 中的“操作”字段中的内容 > SmartDocs删除)后,该模型会从 Edge 组织中删除。这意味着,如果其他门户正在引用该模型,则该模型将不再可用。如需了解详情,请参阅 SmartDoc 模型和模板简介