设计 API

流程

1. 启动 OpenShift 4.x 服务器。
2. 在 Web 浏览器中，导航到浏览器中的 OpenShift 控制台。使用您的凭证登录到控制台。
3. 点 Operators，然后点 OperatorHub。
4. 在搜索字段中，键入 API Designer。
5. 点 API Designer 卡。API Designer operator install 页面将打开。

6. 点 Install。此时会打开 Install Operator 页面。

   1. 对于 Installation mode，请从集群中的命名空间列表中选择一个命名空间（项目），

   2. 对于 Approval Strategy，选择 Automatic 或 Manual 来配置 OpenShift 如何处理对 API Designer Operator 的更新。

      • 如果选择 Automatic 更新，当 API Designer Operator 的新版本可用时，OpenShift Operator Lifecycle Manager (OLM)将自动升级 API Designer 的运行实例，而无需人为干预。
      • 如果选择手动 更新，则当有新版 Operator 可用时，OLM 会创建更新请求。作为集群管理员，您必须手动批准该更新请求，才能将 API Designer operator 更新至新版本。
7. 点 Install 使 API Designer Operator 可供指定命名空间（项目）使用。
8. 要验证项目中是否安装了 API Designer，请点 Operators，然后点 Installed Operators 查看列表中的 API Designer。

1. 在命令窗口中登录到 OpenShift 服务器：

   oc login -u developer -p developer

2. 创建一个新项目命名空间。例如，以下命令创建一个名为 myproject 的新项目：

   oc new-project myproject

3. 运行以下命令，基于 API Designer 模板创建新应用（其中 myproject 是项目的名称）：

   oc new-app -n myproject -f https://raw.githubusercontent.com/jboss-fuse/application-templates/application-templates-2.1.0.fuse-sb2-7_10_0-00015-redhat-00001/fuse-apicurito.yml -p ROUTE_HOSTNAME=myhost

   注： 另外，您还可以在 oc new-app 命令中附加 additional -p 选项来指定其他模板参数。例如，如果您在默认 openshift 命名空间以外的命名空间中安装了 OpenShift 镜像和模板，您可以设置 IMAGE_STREAM_NAMESPACE 指定安装 Fuse 镜像流的命名空间：

   oc new-app -n myproject -f https://raw.githubusercontent.com/jboss-fuse/application-templates/application-templates-2.1.0.fuse-sb2-7_10_0-00015-redhat-00001/fuse-apicurito.yml -p ROUTE_HOSTNAME=myhost -p IMAGE_STREAM_NAMESPACE=othernamespace

4. 运行以下命令，获取 API Designer 部署的状态和 URL：

   oc status

   如果没有部署 API Designer，请运行以下命令验证您是否安装了 apicurito-ui 和 fuse-apicurito-generator 镜像的正确版本：

   oc get is -n openshift | grep "apicurito"

5. 要从浏览器访问 API Designer，请使用提供的 URL （例如 https://apicurito.192.168.64.12.nip.io）。

流程

1. 如果您使用 Fuse Online，请跳至第 2 步。

   如果您在 OpenShift 中使用 Fuse：

   1. 登录您的 OpenShift Web 控制台，然后打开包含 API Designer 的项目。

   2. 对于 OpenShift 4.x，选择 Topology，然后单击 apicurito-service 图标的 URL 链接。

      对于 OpenShift 3.11，从应用程序列表中点击 API Designer 的 URL，例如 https://apidesigner-myproject.192.168.64.43.nip.io

      为 API Designer 打开一个新的浏览器窗口或标签页。

      注意

      因为 API Designer 是 Apicurio Studio 开源项目的 "亮点"版本，"Apicurio"显示在 API Designer 界面中。

2. 单击 New API。此时会打开一个新的 API 页面。

   默认情况下，API Designer 使用 OpenAPI 3 规格。如果要使用 OpenAPI 2 规格，点 New API 按钮旁边的箭头，然后选择 OpenAPI 2。

   注意

   如果您根据 OpenAPI 2 规格打开 API，您可以使用 API Designer 的 Convert to OpenAPI 3 选项转换 API 以符合 OpenAPI 3 规格。

3. 更改 API 名称：

   1. 将光标悬停在名称上，然后点出现的编辑图标( )。
   2. 编辑名称。例如，键入 Task API。
   3. 点勾选标记图标确认名称更改。

4. （可选）：

   • 提供版本号和描述。
   • 添加您的联系信息（名称、电子邮件地址和 URL）。
   • 选择许可证。
   • 定义标签。
   • 定义一个或多个服务器。
   • 配置安全方案。
   • 指定安全要求。

5. 定义 API 的每个端点的相对路径。字段名称必须以斜杠(/)开头。

   对于 Task Management API 示例，创建两个路径：

   • 任务的路径： / libpmem

   • 按 ID: /wagon/{id}的特定任务的路径

     

6. 指定任何路径参数的类型。

   对于 id 参数示例：

   1. 在 Paths 列表中，单击 /bulk/{id}。

      id 参数会出现在 PATH PARAMETERS 部分中。

   2. 点 Create。
   3. 对于描述，键入： 要查找的任务 ID。

   4. 对于类型，选择 integer 作为 32 位整数。

      

7. 在 Data Types 部分中，为 API 定义可重复使用的类型。

   1. 单击 Add a data type。
   2. 在 Add Data Type 对话框中输入名称。对于 Task Management API 示例，键入 Todo。

   3. 另外，您还可以提供一个示例，API Designer 从哪个 API Designer 创建数据类型的 schema。然后您可以编辑生成的模式。

      对于 Task Management API 示例，以以下 JSON 示例开始：

      {
          "id": 1,
          "task": "my task",
          "completed": false
      }

   4. 另外，您可以选择使用数据类型创建 REST 资源。

   5. 点击 Save。如果您提供了一个示例，API Designer 从示例中生成一个模式：

      
8. 另外，您可以添加模式属性并添加新属性。

9. 对于 Task Management API 示例，创建另一个名为 Task 的数据类型，其中包含一个名为 task 的属性，类型为 string。

   

10. 对于每个路径，定义操作(GET、PUT、POST、DELETE、OPTIONS、HEAD 或 PATCH)。

    对于 Task Management API 示例，请按照下表所述定义操作：

    表 3.1. 任务管理 API 操作

    路径	操作	描述	请求正文	响应
    /todo	POST	创建新任务。	介质类型： application/json Data Type: Task	状态代码： 201 Description: 任务创建 响应正文： Media Type: application/json Data Type: Todo
    /todo	GET	获取所有任务。	Not applicable	状态代码： 200 Description : 任务列表
    /todo/{id}	GET	按 ID 获取任务。	Not applicable	Status Code: 200 Description: Task found for ID Response Body: Media Type: application/json Data type: Task Status Code: 404 Description: No tasks with provided identifier found.
    /todo/{id}	PUT	按 ID 更新任务。	Request Body type: Task	Status Code: 200 Description: Completed Status Code: 400 Description: Task not updated
    /todo/{id}	DELETE	按 ID 删除任务。	Not applicable	Status Code: 200 Description: Task deleted Status Code: 400 Description: Task not deleted

11. 解决任何问题，如 解决 API Designer 中的验证问题 中所述。

12. 对于 OpenShift 上的 Fuse，点 Save As 保存您的 API 规格，然后选择 JSON 或 YAML 格式。

    JSON 或 YAML 文件下载到您的本地下载文件夹中。默认文件名是 openapi-spec，带有适当的文件扩展名。

流程

1. 查找由感叹号(!)图标显示的问题。例如：

   

2. 单击感叹号图标以查看问题的描述。例如：

   

3. 根据问题描述提供的信息，导航到问题的位置并修复它。

   例如，要修复"Operation 必须至少有一个响应"问题，请单击 GET 操作以打开它，然后单击 Add a response。

   

   输入响应的描述后，这个问题已解决，感叹号图标会消失：

   

4. 有关所有问题的摘要：

   1. 点右上角的 issues 链接。

      

   2. 点 Go 到一个特定问题的问题，进入问题的位置，以便您可以解决这个问题。

      

流程

1. 在 OpenShift Web 控制台中，打开包含 API Designer 的项目。

2. 打开 API Designer 控制台。在项目的应用程序列表中，点 apidesigner 下的 URL。例如： https://apidesigner-myproject.192.168.64.38.nip.io

   API Designer 控制台会在单独的 Web 浏览器标签页或窗口中打开。

3. 单击 Open API。

   此时会打开文件管理器窗口。

4. 在文件管理器窗口中：

   1. 导航到包含现有 OpenAPI 定义文件的文件夹，如 openapi.json。

   2. 选择 OpenAPI 定义文件，然后点 Open。

      OpenAPI 定义在 API Designer 控制台中打开。

1. 点 Generate。
2. 从下拉列表中选择 Fuse Camel Project。

流程

1. 将 API Designer-generated camel-project.zip 文件解压缩到临时文件夹。
2. Open Red Hat Developer Studio.
3. 在 Developer Studio 中，选择 File → Import。
4. 在 Import 对话框中，选择 Maven → Existing Maven Projects。
5. 在编辑器视图中打开项目的 camel-context.xml 文件。

6. 单击 REST 选项卡，以编辑 Rest DSL 组件。

   有关定义 REST 服务的详情，请参考 Apache Camel 开发指南中的 "定义 REST 服务"部分。

   有关使用 Swagger 支持扩展 JAX-RS 端点的详情，请参考 Apache CXF 开发指南。

   有关使用 Fuse 工具 REST 编辑器的详情，请参考工具 用户指南 的"查看和编辑 Rest DSL 组件"部分。

7. 在 Design 选项卡中，编辑 Camel 路由。

   有关编辑 Camel 路由的详情，请参考 工具用户指南中的"编辑路由上下文"部分。

1. 登录到您的 OpenShift 集群：

   $ oc login -u developer -p developer

2. 为项目创建新的 OpenShift 项目。例如，以下命令会创建一个名为 test-deploy 的新项目。

   $ oc new-project test-deploy

3. 将目录改为包含 Fuse Camel 项目（如 myworkspace/camel-project）的文件夹：

   $ cd myworkspace/camel-project

4. 构建项目并将其部署到 OpenShift 集群：

   $ mvn clean fabric8:deploy -Popenshift

5. 在您的浏览器中，打开 OpenShift 控制台并导航到项目（如 test-deploy）。等待直到您可以看到 camel-project 应用的 pod 已启动。
6. 在项目的 Overview 页面上，找到 camel-project 应用程序的 URL。URL 使用以下格式 ：http://camel-project-MY_PROJECT_NAME.OPENSHIFT_IP_ADDR.nip.io。
7. 单击 URL 以访问该服务。

1. 编辑 Fuse 项目的 pom.xml 文件，使其包含 fabric8-maven-plugin 依赖项，如下例所示：

   <plugin>
           <groupId>org.jboss.redhat-fuse</groupId>
           <artifactId>fabric8-maven-plugin</artifactId>
           <version>${fuse.version}</version>
           <executions>
             <execution>
               <goals>
                 <goal>resource</goal>
                 <goal>build</goal>
               </goals>
             </execution>
           </executions>
     </plugin>

   如果满足某些项目级别条件（例如，项目必须是 Camel Rest DSL 项目），则 Fabric8 Maven 插件将运行 Fabric8 服务发现功能。您不需要将 Fabric8 服务发现 Enricher 指定为 pom.xml 文件中的依赖项，除非您想自定义增强的行为（如 自定义 API 服务注释值 中所述）

2. 在 Fuse Rest DSL 项目的 camel-context.xml 文件中，在 restConfiguration 项中指定以下属性：

   • 方案 ：托管该服务的 URL 的方案部分。您可以指定 "http" 或 "https"。
   • contextPath ：托管 API 服务的 URL 的路径部分。

   • apiContextPath ：托管 API 服务描述文档的位置的路径。如果文档是自托管，则可以指定相对路径，或者指定完整的 URL （如果文档外部托管）。

     以下示例 camel-context.xml 文件显示了 restConfiguration 元素中的注解属性值：

     <?xml version="1.0" encoding="UTF-8"?>
     <beans xmlns="http://www.springframework.org/schema/beans"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="
            http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
            http://camel.apache.org/schema/spring       http://camel.apache.org/schema/spring/camel-spring.xsd">
     
         <camelContext xmlns="http://camel.apache.org/schema/spring">
             <restConfiguration component="servlet" scheme="https"
                   contextPath="myapi" apiContextPath="myapi/openapi.json"/>
     ...

1. 在您选择的编辑器中打开 Fuse 项目的 pom.xml 文件。

2. 找到 fabric8-maven-plugin 依赖项，如下例所示：

   <plugin>
           <groupId>org.jboss.redhat-fuse</groupId>
           <artifactId>fabric8-maven-plugin</artifactId>
           <version>${fuse.version}</version>
           <executions>
             <execution>
               <goals>
                 <goal>resource</goal>
                 <goal>build</goal>
               </goals>
             </execution>
           </executions>
     </plugin>

3. 如以下示例所示，将 Fabric8 服务发现功能作为依赖项添加到 Fabric8-Maven 插件中。

   <plugin>
     <groupId>org.jboss.redhat-fuse</groupId>
     <artifactId>fabric8-maven-plugin</artifactId>
     <version>${fuse.version}</version>
     <executions>
       <execution>
         <goals>
           <goal>resource</goal>
           <goal>build</goal>
         </goals>
       </execution>
     </executions>
     <dependencies>
       <dependency>
         <groupId>io.acme</groupId>
         <artifactId>myenricher</artifactId>
         <version>1.0</version>
         <configuration>
           <enricher>
             <config>
               <f8-service-discovery>
                 <scheme>https</scheme>
                 <path>/api</path>
                 <descriptionPath>/api/openapi.json</descriptionPath>
               </f8-service-discovery>
             </config>
           </enricher>
         </configuration>
         </dependency>
     </dependencies>
   </plugin>

4. 保存您的更改。