4.5. OpenAPI 통합

OpenAPI 서비스를 사용하여 CamelContext 파일에서 REST 정의 경로 및 엔드포인트에 대한 API 문서를 생성할 수 있습니다. 이렇게 하려면 Java 기반인 camel-openapi-java 모듈과 함께 Camel REST DSL을 사용합니다. camel-openapi-java 모듈은 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을 허용할 수 있는지 여부를 감지합니다. 둘 다 허용되거나 지원되는 것으로 설정되지 않은 경우 JSON은 기본 반환 형식입니다.

Apache Camel 3.x 배포에서 camel-example-openapi-cdi 및 camel-example- openapi-java 모듈을 사용하는 방법을 보여줍니다.

Apache Camel 2.x 배포판에서 camel-example-swagger-cdi 및 camel-example-swagger-java 모듈은 camel-swagger-java 모듈을 사용하는 방법을 보여줍니다.

Camel 3.1부터 이름, 설명, 데이터 유형, 매개변수 유형과 같은 매개변수 세부 정보를 정의하여 OpenAPI에서 생성한 문서를 개선할 수 있습니다. XML을 사용하는 경우 이 정보를 추가할 param 요소를 지정합니다. 다음 예제에서는 ID 경로 매개변수에 대한 정보를 제공하는 방법을 보여줍니다.

<!-- 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 를 해당 매개변수 유형으로 지정해야 합니다. 예를 들면 다음과 같습니다.

<!-- 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 배포에서 examples/camel-example-servlet-rest-tomcat 도 참조하십시오.