使用 SmartDocs 记录 API

<ph type="x-smartling-placeholder"></ph> 您正在查看 Apigee Edge 文档。
转到 Apigee X 文档。 信息

。

借助 SmartDocs，您可以在 Drupal 7 开发者门户上记录 API， API 文档提供全面互动。交互式文档意味着门户用户可以：

  • 了解您的 API
  • 向您的 API 发送实时请求
  • 查看从 API 返回的实时响应

通过在您的 API 上创建交互式文档，门户用户可以轻松 学习、测试和评估您的 API

Edge Management API 是一种 RESTful API，可让您使用任意 HTTP 客户端。Apigee 使用 SmartDocs 为 Edge 管理创建交互式文档 API。请点击此处查看该 API 文档。

SmartDocs 门户示例

如需使用 SmartDocs，您必须拥有 Apigee Developer Services 门户。如需了解详情，请参阅 创建开发者 门户网站。

在开发者门户首页，点击顶部导航栏中的 API 以 查看 API 文档页面。

该门户上记录了两个 API：Hello World 和 Pet Store 示例。

Hello World API 是根据模拟目标 OpenAPI 创建的 规范 mocktarget.yaml。如需了解详情，请参阅 https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi。

Pet Store Example API 是根据经典宠物商店演示创建的。

探索 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网址（网址） 按 Tab 键可查看相应的 c网址 调用。

如何使用 SmartDocs 为 API 编写文档

SmartDocs 使用模型来表示您的 API，其中模型包含所有 有关 API 的信息。该门户会从模型中提取 API 相关信息， 将门户上的文档页面渲染为 Drupal 节点，其中每个 Drupal 节点均对应 进入该门户上的文档页面

使用 SmartDocs 的一般步骤如下：

  1. 在门户上配置 Drupal SmartDocs 模块。
  2. 创建 SmartDocs 模型。
  3. 将 API 从 WADL 文件 OpenAPI（以前称为 Swagger）添加到模型 也可以手动创建
  4. 将模型渲染为一组 Drupal 节点。每个 Drupal 节点 包含有关单个 API 的信息。例如，如果 API 中的某个资源同时支持 POST 和 PUT 请求，SmartDocs 将为 POST 和 PUT 创建单独的 Drupal 节点。
  5. 发布 Drupal 节点。发布后，您的门户用户可以查看和 与您的 API 交互
  6. 在发布 Drupal 节点之前或之后修改 Drupal 节点。您可以 使用 Drupal 编辑器或修改原始 WADL 文件来修改 Drupal 节点；或者 OpenAPI 规范修改完 WADL 文件或 OpenAPI 规范后，导入 并将其作为新修订版本放回模型中，然后呈现并发布您所做的更改。
  7. 启用 TLS。由于 SmartDocs 可以将身份验证凭据发送到您的 作为向 API 发出请求的一部分，您应在门户上启用 TLS， 请确保这些凭据是安全的在门户的生产环境和测试环境中 Apigee 提供发出 https:// 请求所需的 TLS 证书。不过，在开始之前 必须获得自己的 TLS 证书并启用 TLS。有关详情，请参阅 在 门户网站。

关于 SmartDoc 模型和模板

在门户中创建模型时，模型实际上存储在 Edge 中 而不是在 Drupal 中模型是一大段 JSON 代码，具有内部名称（例如 “my-smartdocs-api”），它定义了 API 的结构。另一方面，你的门户 以 HTML 形式呈现模型，并为模型提供编辑界面。对 API 的任何更新 将被自动推送回源模型。

存储在组织中

存储在 Drupal 中

模型

模板

具有修改功能的 Drupal 节点

假设您在组织中有多个门户（例如，开发、阶段和 正式版）。在 Pantheon 中，您需要将门户从一个环境迁移到另一个环境。每个 但它似乎包含自己的模型，但所有这些模型 模型。如果您在开发版中修改 API，模型会更新，并且更改会在生产环境中显示。 同样，如果在开发中删除模型，源代码也会一并删除，并且该模型在 生产环境。

模板控制着 SmartDocs 的外观和风格，以及这些模板（由 标识名和 CSS 文件）随每个门户实例一起存储。因此，从理论上讲 对每个模型使用唯一的模板。不过，渲染框架有一项优势， 默认模板（Apigee 默认模板或您提供的模板）会自动 应用于每个模型。

下图显示了模型与门户之间的关系。绿色箭头显示 自动同步。

以下 c网址 命令可列出您组织中的所有模型：

curl -v https://api.enterprise.apigee.com/v1/o/{your_org}/apimodels/ -u edge_org_admin@example.com

配置 SmartDocs 模块

Apigee 将 SmartDocs 实现为自定义 Drupal 模块。按照以下步骤操作 配置 SmartDocs 模块。

<ph type="x-smartling-placeholder">

要配置 SmartDocs 模块，请执行以下操作：

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 在 Drupal 管理菜单中选择模块。全部 已安装的 Drupal 模块。
  3. 启用 SmartDocs 模块。
  4. 保存配置。
  5. 在 Drupal 管理菜单中选择模块。
  6. 选择 SmartDocs ->权限并确保“执行管理” 针对 SmartDocs 模块执行的任务”代表“管理员”角色。
  7. 选择配置 >Drupal 管理界面 菜单。
  8. 将连接超时和请求超时设置为 16 。
  9. 保存配置。
  10. 配置网址设置： <ph type="x-smartling-placeholder">
      </ph>
    1. 选择配置 >搜索和元数据 >网址别名 > 设置。
    2. 设置最大别名长度和组件上限 长度设置为 255。
    3. 展开标点。
    4. 对于左花括号 ({) 和右花括号 (}) 设置中，请选择不执行任何操作（不替换）。
    5. 点击 Save configuration（保存配置）。
  11. 如果您的开发者门户将向内部网络（无权访问 或部分 API 位于专用网络上，请配置 SmartDocs API 代理网址，如下所示： <ph type="x-smartling-placeholder">
      </ph>
    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 或 删除。
  • resourcePath：资源路径。

例如，如果您将内部名称指定为“mymodel”，则生成 针对名为“/books”的资源发出的 GET 请求的 Drupal 节点：

http://prod-myco.devportal.apigee.com/mymodel/apis/get/books

创建模型

创建模型后，模型会作为 API 的来源存储在 Edge 组织中 结构。如需了解详情，请参阅关于 SmartDoc 模型和 模板。

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 选择内容 >Drupal 管理中的 SmartDocs 菜单。
  3. 选择页面顶部的新建模型。
  4. 输入以下字段： <ph type="x-smartling-placeholder">
      </ph>
    • 名称：将在整个网站中显示的模型名称。
    • 内部名称：输入名称时，内部 名称。模型的内部名称，该名称在所有模型中必须是唯一的。 内部名称只能包含小写字母、数字和连字符，不能有空格。 选择修改以修改此名称。
    • 说明：对模型的说明。
  5. 选择创建模型。

创建模型后，您将被重定向到该模型的页面。然后，您可以使用 “操作”下拉菜单 bx 可以执行以下操作：

  • 导入一个描述您的 API 的 WADL 文件或指定 OpenAPI 的网址 描述 API 的规范。
  • 向模型添加修订版本
  • 修改模型设置，包括 模型。
  • 将模型导出到文件中。
  • 删除模型。

向模型添加 API

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

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

您还可以将 SmartDocs JSON 文件导入模型。此文件通常由 首先导出现有模型，修改文件，然后导入更新。如需了解详情， 请参阅“导出和导入模型”。

视频：观看一小段视频，了解如何通过以下方法向 SmartDocs 模型添加 API 如何导入 OpenAPI 规范

导入 WADL

成功创建模型后，导入描述 API 的 WADL 文件。每个 导入 WADL 文件时，系统会自动创建模型的新修订版本。

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

导入 OpenAPI 规范

成功创建模型后，您可以导入 OpenAPI（以前称为 Swagger） 规格设计阶段。Edge 支持 OpenAPI 1.2 和 2.0 版。

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

<ph type="x-smartling-placeholder">

如需导入 OpenAPI 规范，请执行以下操作：

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 选择 内容 >SmartDocs Drupal 管理菜单。
  3. 选择要更新的模型。
  4. 在操作下，选择导入。
  5. 在 SmartDocs 导入页面上的选择格式下拉菜单。
  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. 为每个资源定义一个或多个方法。方法指定可被 调用该方法。例如，对于“/login”您可以支持使用 POST 登录和 DELETE 用于退出。此资源不支持其他 HTTP 动词，例如 PUT 或 GET。 因此，您需要为资源定义两个方法，一个用于 POST，另一个用于 DELETE。

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

作为一般的规则：

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

创建模型的新修订版本

您只能向模型的现有修订版本添加资源。如果模型已有 您可以添加自己的资源如果模型是新模型且没有修订版本，请创建一个新模型 修订版本

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

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

定义资源

资源指定 API 的完整网址。定义资源时，您可以指定 资源路径，该路径与模型修订版本中的基准网址组合以创建完整网址 资源。

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

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 选择 内容 >智能文档 Drupal 管理菜单
  3. 对于要更新的模型，在操作下，选择 API 修订版本：查看模型的所有修订版本。
  4. 选择要修改的修订版本。
  5. 在修订版本页面上，从下拉菜单中选择添加资源。
  6. 在 Add Resource 页面上，输入以下信息： <ph type="x-smartling-placeholder">
      </ph>
    • 显示名：资源的名称。
    • 路径：资源路径，以“/”开头。 路径与模型修订版本的基准网址合并到一起 创建资源的完整网址。
    • 说明：对资源的说明。
    • 参数：（可选）输入定义每个参数的 JSON 对象 资源。这些参数如下所述。
  7. 选择添加资源。您会被重定向到模型页面。现在，您可以 定义方法

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

或者，您也可以在方法上定义参数。例如，POST 方法可能支持 。因此，请将任何参数 在定义方法时指定某个方法，如下所述。

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

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

类型

JSON 对象

备注

模板

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

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

description 值 。

查询

{
"dataType": "string",
"defaultValue": "",
"description": "营业地点。",
"name": "w",
"required": true,
"type": "QUERY"
}

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

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

标题

{
"dataType": "string",
"defaultValue": "应用/json",
"description": "指定为 <code>application/json</code>。",
"name": "内容类型",
"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_name 和 developer_email 部分，然后再 他们可以提交请求

定义方法

为每个资源定义一个或多个方法。方法定义指定了 HTTP 动词 可在资源上调用的类您可以为一个资源定义一个方法，或者 方法。

在定义方法时，请指定方法使用的所有参数，包括查询和 标头参数中。请参阅上述说明，了解有关添加参数的资源 方法。

下图显示了 Apigee Create Developer API 的现有 SmartDocs 页面 以您在定义 方法：

下图显示了同一页面，但选择了“请求正文的说明”：

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

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 选择 内容 >智能文档 Drupal 管理菜单
  3. 对于要更新的模型，在操作下，选择 API 修订版本：查看模型的所有修订版本。
  4. 选择要修改的修订版本。
  5. 在修订版本页面上，从下拉菜单中选择 Add Method（添加方法）中某一项。 资源。
  6. 在 Edit Method（修改方法）页面上，输入以下信息： <ph type="x-smartling-placeholder">
      </ph>
    • 显示名：API 的名称，它也会成为 此 API 的 Drupal 页面。
    • 说明：描述 API。
    • 方法 动词：HTTP 动词类型。
    • 安全架构：指定身份验证模式（如果有） 方法。如需了解详情，请参阅配置 SmartDocs 身份验证 type。
    • 内容类型：请求和响应的内容类型。请参阅 部分，了解如何配置不同的身份验证方法。
    • 参数 (Parameters)：（可选）方法的任何查询或标头参数。 如需了解详情，请参阅上文说明，了解如何向资源添加参数。
    • 请求正文文档：（可选）描述请求正文。发布 和 PUT 方法接受请求正文。您可以使用此区域对其进行描述。如果您省略此参数 值，则省略 Request Body 下的 Description 链接 从生成的 SmartDocs 页面中找到。
    • 请求正文示例：（可选）显示请求正文示例。 通常是 JSON 对象或 XML 格式对于 POST 和 PUT 动词，请求正文 示例会作为每个请求的一部分进行传递。SmartDocs 页面的用户可编辑此内容 然后再向 API 提交请求。如果您省略此值，则 请求正文下的值链接已从 生成的 SmartDocs 页面。
    • Tags：与 API 相关联的一组标记。SmartDocs 会使用标记来 将类似的 API 归为一组。例如，您可以将“统计信息”代码到所有 API 有关统计信息的知识。您可以将来自不同资源的 API 归入一个标记。如果它们 它们都使用相同的标记
  7. 选择 Add Method（添加方法）。您会被重定向到模型页面。现在，您可以 呈现和发布您的方法

渲染模型

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

您可以选择一次渲染整个模型，也可以为 呈现。

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

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

您不必选择渲染节点，而是可以选择渲染 和发布节点，以 Drupal 节点呈现并立即发布 API。

发布节点

节点在发布之前对门户用户不可见。您可以视需要选择 在渲染过程中发布节点如果选择不发布节点 则必须在呈现完成后手动发布它们

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

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 选择 内容 > Drupal 管理菜单
  3. 针对要发布的模型，选择 API Revisions（API 修订版本） 运维套件。
  4. 选择要发布的修订版本。您只能发布单个修订版本中的节点 模型。
  5. 选择要发布的方法。
  6. 选择要发布的修订版本中的节点。
  7. 从 Update 中选择 Publish Nodes（发布节点）。 options 下拉菜单。
  8. 点击更新。
  9. 通过选择节点关联下的节点 ID 导航到该节点 列。

默认情况下，已发布 API 节点的 Drupal 网址采用以下格式：http://<drupalBasePath>/<internalName>/apis/<httpMethod>/<resourcePath>。drupalBasePathdrupalBasePathdrupalBasePathdrupalBasePath 请按照以下步骤控制网址格式：

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

由于门户上有缓存，您可能无法立即看到模型页面显示 。如有必要，您可以使用 以下程序：

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

取消发布节点

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

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

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 选择 内容 > Drupal 管理菜单
  3. 针对要取消发布的模型，选择下方的 API Revisions（API 修订版本） 运维套件。
  4. 选择要取消发布的节点的模型修订版本。
  5. 选择要取消发布的修订版本中的节点。
  6. 从 Update 中选择 Unpublish 节点 options 下拉菜单。
  7. 点击更新。

查看模型的修订版本

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

您可以同时渲染和发布多个修订版本中的节点。也就是说，如果 则可以发布任意或所有修订版本中的节点。不过，发布 如果一个模型中的 API 与另一个模型的已发布节点相同，则系统会取消发布旧的 并替换为最近发布的版本 API。

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

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 选择 内容 > Drupal 管理菜单
  3. 对于要更新的模型，选择 API Revisions（API 修订版本） 运维套件。
  4. 选择要查看的模型修订版本。
  5. 按照上述说明渲染和发布节点。

修改节点

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

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

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

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

或者，您也可以在 SmartDocs 模型中修改节点：

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 选择 内容 > Drupal 管理菜单
  3. 对于要更新的模型，选择 API Revisions（API 修订版本） 运维套件。
  4. 选择要发布的模型修订版本。
  5. 从操作下拉菜单中选择修改方法 方法。

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

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 选择 内容 > Drupal 管理菜单
  3. 对于要更新的模型，选择 API Revisions（API 修订版本） 运维套件。
  4. 选择要发布的模型修订版本。
  5. 在以下位置选择删除方法： 方法的操作下拉列表。
    注意：删除节点也会从模型中移除 API。如果您仅 您想要取消发布此 API 以对门户用户隐藏，但不想将其删除 则应按照上述说明取消发布该节点。

该门户拥有内置报告，其中会显示由 SmartDocs 模型不再引用模型的有效方法。通过以下方式访问报告： 在 Drupal 菜单中选择报告，然后选择相应报告 名为 SmartDocs 节点状态。

导出和导入模型

借助 SmartDocs，您可以将现有模型导出到文件中。例如，您可以定义 生产环境和预演环境然后，在预演环境中进行所有 SmartDocs 编辑 环境准备好发布 API 后，您可以导出和导入预演模型 引入生产模型。

导入模型会创建模型的新修订版本。SmartDocs 会尝试匹配现有 包含导入的 API 的模型中的 API。如果 SmartDocs 检测到匹配项，导入操作就会更新 Drupal 现有 API 对应的节点。如果 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. 选择以下位置中的文件或网址： 上传类型： <ph type="x-smartling-placeholder">
      </ph>
    1. 如果选择 File，请浏览至 JSON 文件。
    2. 如果您选择网址，请指定 SmartDocs JSON 文件的网址。
  6. 点击导入，将其导入到模型中。
  7. 系统会将您重定向到相应模型的信息页面，您现在可以在此页面中 模型。请注意，导入操作会创建模型的新修订版本。
  8. 渲染并发布节点。

编辑 SmartDocs 模板

SmartDocs 模板定义了 Drupal 节点在屏幕上的显示方式。每个 SmartDoc 模型可以使用同一默认模板，也可以手动自定义用于 单个模型。

SmartDocs 模板包含一个编码为 Handlebars .hbr 文件的模板文件， 和 JavaScript 文件在 Handlebars 中，许多内容都是使用嵌入式 句柄表达式，例如 &123;&123;body}}。现有 手柄表达式在文件顶部的注释中提供。有关 使用 Handlebars 自定义模板，请参阅 http://handlebarsjs.com。

以下部分介绍了如何上传供所有人使用的自定义 SmartDocs 模板文件。 或者在将新 API 导入现有模型时，如何恢复 原始默认 SmartDocs 模板文件，以及如何修改 单个模型。

上传自定义 SmartDocs 模板文件

您可以上传自定义 SmartDocs 模板文件（作为 Handlebars .hbr 文件），以用作 默认模板。

如果您希望使用默认的 SmartDocs 模板文件来创建 您的自定义 SmartDocs 模板文件，可以从： profiles/apigee/modules/custom/devconnect/smartdocs/templates/smartdocs.hbr

要上传自定义 SmartDocs 模板文件，请执行以下操作：

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

恢复 默认 SmartDocs 模板文件

您可以恢复默认的 SmartDocs 模板文件。恢复之后，默认的 模板文件，在创建新模型或将新 API 导入现有模型时将会用到 模型。

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

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

正在修改 单个模型的 SmartDocs 模板

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

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

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 选择 内容 > Drupal 管理菜单
  3. 对于要修改的模型，选择下方的设置 运维。
  4. 在 方法模板 区域中，根据需要编辑模板。
  5. 点击保存模板。
  6. 浏览到 Drupal 节点。您应该会在页面上看到模板更改。

配置 SmartDocs 身份验证类型

SmartDocs 中定义的 API 可以是开放的 API，这意味着没有身份验证凭据 访问它们所需的资源，或确保安全。安全的 API 要求您在创建 该 API 调用。

为了实现安全的 API，SmartDocs 支持以下类型的身份验证：

  • 基本身份验证 - 将基本身份验证凭据作为 用户名和密码对。如果您没有指定使用 OAuth 作为凭据类型， 默认使用基本身份验证。
  • OAuth 2.0：由第三方服务提供商对用户进行身份验证 凭据，确保用户获得 API 授权，然后授予访问 令牌。当您向受保护的 API 发出 SmartDocs 请求时，SmartDocs 会构建该请求并 并将其发送给服务提供商然后，服务提供商会验证该令牌 确认其未过期
  • 自定义令牌 - 将令牌值作为标头或查询参数传递给每个 请求。

对于每种身份验证类型，您都需要创建安全机制，以定义 身份验证特性。例如，对于自定义令牌身份验证， 安全机制定义了令牌的传递方式（标头、查询参数、正文参数）以及 令牌。

安全方案与模型的特定修订版本相关联。因此，如果您创建 模型的新修订版本时，就必须重新定义该修订版本的安全方案

在 WADL 文件中，您可以使用 &lt;apigee:authentication&gt; Apigee 标记来指定 API 是否需要身份验证，如下所示： 如下所示：

<method id="statusespublic_timeline" name="GET" apigee:displayName="PublicTimeline">
    ...
    <apigee:authentication required="true"/>
</method>

如果 API 是开放 API，请将 required 属性设为 false。

请注意，您无法在 WADL 文件中指定身份验证类型。为此，您需要 如何在 Drupal 中修改节点。如需详细了解 WADL 文件，请参阅 WADL 参考文档。

在 Drupal 的 API 页面上，SmartDocs 添加了以下按钮，以便用户指定自己的 基本身份验证凭据：

如果您修改节点以将身份验证类型设置为 OAuth，则 SmartDocs 会将 以下按钮添加到网页：

对于自定义令牌，SmartDocs 会添加：

正在配置 基本身份验证

如果您对 API 使用基本身份验证，则只需在 WADL 中指定 &lt;apigee:authentication&gt; 标记 文件。

如需将基本身份验证应用于通过 WADL 文件以外的来源创建的方法，请执行以下操作：

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 选择 内容 > Drupal 管理菜单
  3. 针对所需的模型，选择 API Revisions（API 修订版本） 运维套件。
  4. 针对要修改的模型修订版本，选择安全性 Settings（位于 Operations 下）。
  5. 选择添加安全方案。
  6. 指定安全方案的名称。
  7. 选择基本作为类型。
  8. 选择提交。
  9. 对于模型中的每个方法，修改方法以设置其安全方案 基本方案
    1. 选择 内容 > Drupal 管理菜单
    2. 针对所需的模型，选择 API Revisions（API 修订版本） 运维套件。
    3. 针对要修改的模型修订版本，选择修订版本 Details（位于操作下）。
    4. 为要修改的 API 选择 Edit Method（修改方法）。
    5. 为该 API 选择安全方案。
    6. 保存该 API。

正在配置 OAuth 2.0 身份验证

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

  1. 在安全性 设置。
  2. 为以下模型的所有修订版本指定客户端 ID 和客户端密钥 模型的设置。
。

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

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 选择 内容 > Drupal 管理菜单
  3. 对于所需的模型，选择“操作”下的 API 修订版本。
  4. 对于要修改的模型修订版本，请选择 Security Settings（安全设置） 运维。
  5. 选择添加安全方案。
  6. 指定安全方案的名称。
  7. 选择 OAuth 2.0 作为类型。
  8. 设置授权类型。
  9. 在授权网址字段中输入值。授权 网址用于获取访问令牌。
  10. 将授权动词设置为 GET 或 POST。
  11. 输入访问令牌网址。访问令牌网址是用来 用请求令牌交换访问令牌。
  12. 输入访问令牌参数名称。
  13. 使用 In 指定如何传递令牌：Header、 Query 或 Body。
  14. 设置 OAuth 范围。
  15. 选择提交。
  16. 选择 内容 > Drupal 管理菜单
  17. 对于模型，请在操作中选择设置 下拉菜单中。
  18. 在客户端 ID 和客户端 ID 中输入值 Secret。
  19. 选择保存模板身份验证设置。
  20. 对于模型中的每个方法，修改方法以设置其安全方案 OAuth 安全机制
    1. 选择 内容 > Drupal 管理菜单
    2. 针对所需的模型，选择 API Revisions（API 修订版本） 运维套件。
    3. 针对要修改的模型修订版本，选择修订版本 Details（位于操作下）。
    4. 为要修改的 API 选择 Edit Method（修改方法）。
    5. 为该 API 选择安全方案。
    6. 保存该 API。

配置自定义令牌身份验证

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

要启用自定义令牌，请按以下步骤操作：

  1. 以拥有管理员或内容创建权限的用户身份登录门户。
  2. 选择 内容 > Drupal 管理菜单
  3. 针对所需的模型，选择 API Revisions（API 修订版本） 运维套件。
  4. 针对要修改的模型修订版本，选择安全性 Settings（位于 Operations 下）。
  5. 选择添加安全方案。
  6. 指定安全方案的名称。
  7. 选择 Apikey 作为类型。
  8. 设置包含令牌的 Param 名称。
  9. 使用 In 指定如何传递 token：Header、Query、 或 Body。
  10. 选择提交。
  11. 对于模型中的每个方法，修改方法以设置其安全方案 与您的令牌方案相关联。
    1. 选择 内容 > Drupal 管理菜单
    2. 针对所需的模型，选择 API Revisions（API 修订版本） 运维套件。
    3. 针对要修改的模型修订版本，选择修订版本 Details（位于操作下）。
    4. 为要修改的 API 选择 Edit Method（修改方法）。
    5. 为该 API 选择安全方案。
    6. 保存该 API。

删除模型

当您删除模型（内容 > SmartDocs、删除 Drupal 中的 Operations 字段），模型会从您的 Edge 组织中删除。也就是说，如果 其他门户正在引用该模型，则该模型不再可用。如需更多信息 请参阅关于 SmartDoc 模型和模板。