swagger-ui에서 API 문서를 게시하는 방법

이번에는 swagger-ui를 Fuse 애플리케이션에 내장하고 API 문서(WebAPI 사양서)를 쉽게 공개하는 샘플과 설정 내용을 소개합니다.

이 샘플에서는 Swagger UI를 사용하여 RES DSL에 정의된 API의 API 문서(WebAPI 사양)를 표시합니다.

소스 코드는 Github ([https://github.com/jian-feng/camel-restdsl-swagger-demo.git])에서 다운로드할 수 있습니다.

Swagger UI 및 Camel REST DSL

Swagger 은 RESTful API 문서, 서버, 클라이언트 코드, 편집기, 그리고 그것들을 다루기 위한 사양 등을 제공하는 프레임워크입니다.

Swagger UI 은 Swagger Specification 에서 동적으로 문서를 생성하는 도구입니다.

RES DSL은 Camel 루트에서 REST API를 설명하는 DSL입니다.

덧붙여 REST DSL로 REST API를 개발하는 방법은, 이 기사를 참조해 주세요.

Creating a REST API in Apache Camel

Get started with REST services with Apache Camel

29줄로 메일 보내기 서비스 만들기 - Apache Camel

이번에는 REST DSL 개발이 아니라 주로 Swagger UI 연동을 위한 설정을 설명하겠습니다.

샘플 실행 방법

Maven 명령으로 실행합니다.

mvn spring-boot:run

그런 다음 브라우저에서 샘플 앱에 게시된 Swagger UI를 볼 수 있습니다.

http://localhost:8080/webjars/swagger-ui/3.22.0/index.html?url=/camel/api-docs

샘플 설정 내용

Step 0. Swagger UI 내장

pom.xml 에 Swagger 라이브러리를 추가합니다.

<!-- Swagger support for restdsl -->
<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-swagger-java-starter</artifactId>
</dependency>
<dependency>
    <groupId>org.webjars</groupId>
    <artifactId>swagger-ui</artifactId>
    <version>${swagger.ui.version}</version>
</dependency>

Step 1. REST Configuration

Camel 제공 Swagger 설정 항목을 사용하여 전체 API의 개요 정보를 Rest configuration( camel-context.xml 의 <restConfiguration> )에 설명합니다.

예:

<restConfiguration apiComponent="swagger"
    apiContextPath="/api-docs" component="servlet"
    contextPath="/camel" enableCORS="true" host="0.0.0.0" port="8080">
    <dataFormatProperty key="prettyPrint" value="true"/>
    <!-- 設定可能なapiProperty一覧は、Swaggerドキュメントを参照 -->
    <!-- http://swagger.io/specification/#infoObject -->
    <apiProperty key="api.title" value="My REST API"/>
    <apiProperty key="api.version" value="1.0.0"/>
    <apiProperty key="api.description" value="APIドキュメントのデモ"/>
    <apiProperty key="api.contact.name" value="フェン　ジン"/>
    <apiProperty key="api.contact.email" value="[email protected]"/>
</restConfiguration>

apiComponent, apiContextPath 다른 설정 가능한 내용은 여기을 참조하십시오.

enableCORS 는 API 정보(infoObject) 설정입니다. 다른 설정 가능한 내용은 여기을 참조하십시오.

Step 2. REST Context

Camel 제공 Swagger 설정 항목을 사용하여 개별 API 세부 정보(예: 요청/응답 데이터 유형 등)를 Rest context( <apiProperty> 의 camel-context.xml )에 설명합니다.

Rest context를 별도의 XML로 작성하고 Camel-context.xml에서 include할 수도 있습니다.

예:

<rest bindingMode="off" id="rest-1" path="/restsvc">
    <description>sample rest service</description>
    <get id="get-1" uri="/ping">
        <description>This is ping service</description>
        <responseMessage code="200"
            message="要求情報が正常に処理され、HelloメッセージがJSON形式で返す" responseModel="org.mycompany.ResponseInfo"/>
        <responseMessage code="500"
            message="要求情報に問題がないが、サーバ側で処理異常のため、ErrorメッセージがJSON形式で返す" responseModel="org.mycompany.ErrorInfo"/>
        <route>
            <to uri="direct:hello"/>
        </route>
    </get>
</rest>

<rest> 다른 설정 가능한 내용은 여기을 참조하십시오.

Step 3. DataModel

Swagger Core의 모델 속성 정의( @ApiModelProperty ) 어노테이션을 사용하여 개별 DataModel에 추가 정보를 추가합니다.

요청 및 응답 정보의 데이터 모델과 리소스 모델에서 정의한 각 속성에 <description>를 사용하여 속성 설명, 입력 예제, 속성 표시 순서 등을 설정할 수 있습니다. 다음은 주요 방법을 설명합니다.

メソッド        説明  
value       プロパティ名を指定します。  
required        プロパティが必須かどうかを指定します。 (default: false)  
example     プロパティの入力例を指定します。  
position        プロパティの表示順序を指定します。 (default: 0)  

예 : <responseMessage>

import io.swagger.annotations.ApiModelProperty;

public class ResponseInfo {
    @ApiModelProperty(value = "Hello msg from camel", required = true, example = "sample message")
    private String msg;

    public String getMsg() {
        return msg;
    }

    public void setMsg(String msg) {
        this.msg = msg;
    }
}

끝에

Camel의 REST DSL로 개발된 API는 camel-swagger를 통해 API 문서를 게시하는 방법을 이해할 수 있었습니까? API를 개발할 때 소스 코드에서 주석뿐만 아니라 게시 가능한 API 정보도 의식하고 포함하면 쉽게 정보 공유할 수 있습니다. 이러한 이유로 개발 표준의 일부로 통합하십시오.