4.5. OpenAPI 集成

您可以使用 OpenAPI 服务为 CamelContext 文件中的任何 REST 定义路由和端点创建 API 文档。为此，请使用带有 camel-openapi-java 模块的 Camel REST DSL，该模块纯是基于 Java 的。camel-openapi-java 模块会创建一个 servlet，它与 CamelContext 集成，并从每个 REST 端点拉取信息，以 JSON 或 YAML 格式生成 API 文档。

如果使用 Maven，请编辑 pom.xml 文件，以对 camel-openapi-java 组件添加依赖项：

<dependency>
   <groupId>org.apache.camel</groupId>
   <artifactId>camel-openapi-java</artifactId>
   <version>x.x.x</version>
   <!-- Specify the version of your camel-core module. -->
</dependency>

要在 Camel REST DSL 中启用 OpenAPI，请调用 apiContextPath （） 来设置 OpenAPI 生成的 API 文档的上下文路径。例如：

public class UserRouteBuilder extends RouteBuilder {
    @Override
    public void configure() throws Exception {
        // Configure the Camel REST DSL to use the netty4-http component:
        restConfiguration().component("netty4-http").bindingMode(RestBindingMode.json)
            // Generate pretty print output:
            .dataFormatProperty("prettyPrint", "true")
            // Set the context path and port number that netty will use:
            .contextPath("/").port(8080)
            // Add the context path for the OpenAPI-generated API documentation:
            .apiContextPath("/api-doc")
                .apiProperty("api.title", "User API").apiProperty("api.version", "1.2.3")
                // Enable CORS:
                .apiProperty("cors", "true");

        // This user REST service handles only JSON files:
        rest("/user").description("User rest service")
            .consumes("application/json").produces("application/json")
            .get("/{id}").description("Find user by id").outType(User.class)
                .param().name("id").type(path).description("The id of the user to get").dataType("int").endParam()
                .to("bean:userService?method=getUser(${header.id})")
            .put().description("Updates or create a user").type(User.class)
                .param().name("body").type(body).description("The user to update or create").endParam()
                .to("bean:userService?method=updateUser")
            .get("/findAll").description("Find all users").outTypeList(User.class)
                .to("bean:userService?method=listUsers");
    }
}

下表中描述的选项可让您配置 OpenAPI 模块。设置如下选项：

从 Camel 3.1 开始，camel-openapi-java 模块支持 JSON 和 YAML 格式的输出。要指定输出，将 /openapi.json 或 /openapi.yaml 添加到请求 URL。如果请求 URL 没有指定格式，则 camel-openapi-java 模块将检查 HTTP Accept 标头以检测是否可以接受 JSON 或 YAML。如果接受或不将 none 设置为 accepted，则 JSON 是默认的返回格式。

在 Apache Camel 3.x 分发中，camel-example-openapi-cdi 和 camel-example-openapi-java 演示了 camel-openapi-java 模块的使用。

在 Apache Camel 2.x 发行版本中，camel-example-swagger-cdi 和 camel-example-swagger-java 演示了 camel-swagger-java 模块的使用。

从 Camel 3.1 开始，您可以通过定义名称、描述、数据类型、参数类型等参数详情来增强 OpenAPI 生成的文档。如果使用 XML，请指定 param 元素来添加此信息。以下示例演示了如何提供 ID path 参数的信息：

<!-- This is a REST GET request to view information for the user with the given ID: -->
<get uri="/{id}" outType="org.apache.camel.example.rest.User">
     <description>Find user by ID.</description>
     <param name="id" type="path" description="The ID of the user to get information about." dataType="int"/>
     <to uri="bean:userService?method=getUser(${header.id})"/>
</get>

以下是 Java DSL 中的相同示例：

.get("/{id}").description("Find user by ID.").outType(User.class)
   .param().name("id").type(path).description("The ID of the user to get information about.").dataType("int").endParam()
   .to("bean:userService?method=getUser(${header.id})")

如果您定义了名称为 body 的参数，那么您还必须将 body 指定为该参数的类型。例如：

<!-- This is a REST PUT request to create/update information about a user. -->
<put type="org.apache.camel.example.rest.User">
     <description>Updates or creates a user.</description>
     <param name="body" type="body" description="The user to update or create."/>
     <to uri="bean:userService?method=updateUser"/>
</put>

以下是 Java DSL 中的相同示例：

.put().description("Updates or create a user").type(User.class)
     .param().name("body").type(body).description("The user to update or create.").endParam()
     .to("bean:userService?method=updateUser")

另请参阅 Apache Camel 分发中的 example/camel-example-servlet-rest-tomcat。