设计 API

流程

1. 在 Web 浏览器中，打开 OpenShift 控制台并使用您的凭据（例如，用户名 developer 和密码 developer）登录。
2. 选择包含 API Designer 操作器的项目。

3. 选择 Topology，并确认您看到标有 fuse-apicurito 的图标。

   如果有用于 apicurito-service-ui 和 apicurito-service-generator 的图标，您的 OpenShift 管理员已将 API Designer 添加为项目，您可以跳过这些步骤的其余部分。

   如果没有用于 apicurito-service-ui 和 apicurito-service-generator 的图标，请继续下一步。

4. 在左侧导航窗格中，单击 Add+。
5. 在 Developer Catalog 部分下，单击 Operator Backed。
6. 在搜索字段中，键入 Apicurito 来过滤目录项。
7. 单击 由红帽卡提供的 Apicurito。

8. 点 Create。

   此时会打开 API Designer 实例的最小起始模板的默认表单。接受默认值，或者（可选）编辑它们。

9. 点 Create 以触发新 API Designer 实例的 pod、服务和其他组件的启动。
10. 要验证 API Designer 服务是否已添加到项目中，请选择 Topology，然后确认您看到 apicurito-service-ui 和 apicurito-service-generator 的图标。
11. 要打开 API 设计器，请单击 apicurito-service-ui 图标上的 URL 链接。

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-7_13_0-00014-redhat-00001/fuse-apicurito.yml -p ROUTE_HOSTNAME=myhost

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

   oc new-app -n myproject -f https://raw.githubusercontent.com/jboss-fuse/application-templates/application-templates-2.1.0.fuse-7_13_0-00014-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-ui 图标上的 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 到 OpenAPI 3 选项，来转换 API 以符合 OpenAPI 3 规格。

3. 更改 API 名称：

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

4. （可选）：

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

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

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

   • 任务的路径： /setuptools

   • 一个特定任务的路径，按 ID: / covers/{id}

     

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

   对于示例 id 参数：

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

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

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

   4. 对于类型，将 整数 选为 32 位整数。

      

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

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

   3. 另外，您可以提供一个示例，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 的数据类型，其名为 string 的任务。

   

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

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

    表 3.1. 任务管理 API 操作

    路径	操作	描述	请求正文	响应
    /todo	POST	创建新任务。	media Type: application/json Data Type: Task	Status Code: 201 Description: Task created 响应正文： Media Type: application/json Data Type: Todo
    /todo	GET	获取所有任务。	Not applicable	Status Code: 200 Description : 任务列表
    /cleanup/{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 task with provided identifier found.
    /cleanup/{id}	PUT	按 ID 更新任务。	request Body type: Task	Status Code: 200 Description: Completed Status Code: 400 Description: Task not updated
    /cleanup/{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，然后选择 JSON 或 YAML 格式来保存您的 API 规格。

    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. 打开 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 文件，使其包含 openshift-maven-plugin 依赖项，如下例所示：

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

   如果满足某些项目级别条件（例如，项目必须是 Camel Rest DSL 项目），则 OpenShift Maven 插件将运行服务发现Enricher。您不需要将 Service Discovery 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. 找到 openshift-maven-plugin 依赖项，如下例所示：

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

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

   <plugin>
     <groupId>org.jboss.redhat-fuse</groupId>
     <artifactId>openshift-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. 保存您的更改。