4.5. Swagger 集成

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

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

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

要在 Camel REST DSL 中启用 Swagger API，请调用 apiContextPath （） 来设置 Swagger 生成的 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 Swagger-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");
    }
}

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

如果您使用 Swagger 用户界面查看您的 REST API 文档，则可能需要启用对 HTTP 访问控制(CORS)的支持。当 Swagger 用户界面托管并在主机名/端口上运行时，需要这个支持，它与运行 REST API 的主机名/端口不同。

要启用对 CORS 的支持，请将 RestSwaggerCorsFilter 添加到 web.xml 文件中。CORS 过滤器添加启用 CORS 的 HTTP 标头。例如：

<!-- Enable CORS filter to allow use of Swagger UI for browsing and testing APIs. -->
<filter>
     <filter-name>RestSwaggerCorsFilter</filter-name>
     <filter-class>org.apache.camel.swagger.rest.RestSwaggerCorsFilter</filter-class>
</filter>
<filter-mapping>
     <filter-name>RestSwaggerCorsFilter</filter-name>
     <url-pattern>/api-docs/*</url-pattern>
     <url-pattern>/rest/*</url-pattern>
</filter-mapping>

RestSwaggerCorsFilter 为所有请求设置以下标头：

RestSwaggerCorsFilter 是一个简单的过滤器。如果您需要阻止某些客户端或为给定客户端设置标题值，您可能需要更复杂的过滤器。

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

在 Apache Camel 分发中，camel-example-swagger-cdi 和 camel-example-swagger-java 演示使用 camel-swagger-java 模块。

从 Camel 2.16 开始，您可以通过定义名称、描述、数据类型、参数类型等参数详情来增强 Swagger 生成的文档。如果使用 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。