[Java] Armeria Documentation Service 생성하기

 

Armeria에서는 간단하게 구현이 가능한 API Document에 대한 기능을 제공합니다

 

Armeria에서 제공하는 기능이 너무나도 간단하고 편리해서

 

해당 기능을 사용하면 API Documentation 과정에 소요되는 시간을 매우 효율적으로 사용할 수 있습니다

 

이번 글에서는 Armeria에서 제공하는 Document Service를 사용해보겠습니다

 

참고로 본 글은 Armeria Restful API Service가 존재함을 전제합니다.

 

 

아직 Armeria API 서버를 생성하지 않았다면, 아래 과정을 따라오시는 것을 추천드립니다

- [Java] Armeria - Restful API 서버 구축하기 - (1) Application 생성

- [Java] Armeria - Restful API 서버 구축하기 - (2) 도메인서비스 연동

 

 

 

Armeria Document Service를 구현하는 과정은 매우 단순합니다.

 

Document Service를 생성하고 -- (1)

Armeria Server에 등록하면       -- (2)

끝입니다.

 

 

Document Service 생성 -- (1)

DocService docService = DocService
                .builder()
                // 전역
                .exampleHeaders(BookService.class,
                                HttpHeaders.of("accept","application/json"))
                //findAll
                .exampleRequests(BookService.class,
                                 "findAll")
                //findById
                .examplePaths(BookService.class,
                              "findById",
                              "/book/1")
                .exampleQueries(BookService.class,
                                "findById",
                                "search=123")
                .exampleQueries(BookService.class,
                                "findById",
                                "search=456")
                //createBook
                .exampleRequests(BookService.class,
                                 "createBook",
                                 new Book(123, "name", 256).toJson())           
                .build();

 

 

• exampleRequests() : 요청 데이터  (주로 RequestBody) 의 예시를 등록합니다
• exampleQueries() : Request Parameter 예시를 등록합니다
• examplePaths() : QueryString 예시를 등록합니다

 

하나의 서비스 메서드에 여러가지 예시 데이터를 등록할 수 있습니다

각 메서드의 인자 값 중, 요청 서비스의 메서드명을 직접 명시하지 않으면, 전역 값으로 등록됩니다

 

 

Armeria Service 등록  -- (2)

sb.http(Main.PORT)
     .annotatedService(new BookService())
     .serviceUnder("/book/docs", docService)
     .build();

 

 

서비스 등록은 더 쉽습니다.

Armeria Server Builder에 Docmuentation Service의 URL Prefix와 생성한 DocService 인스턴스를 등록하면 끝입니다

 

 

Armeria Document Service 접근

 

 

요청 예시

 

 

Armeria Document Service는 URL 경로를 통해 각 서비스 메서드를 동적 바인딩하여 등록하기에

 

개발자가 각 서비스 메서드를 직접 명시하는 수고를 덜었다는 점은 Armeria Documentation의 장점이라고 볼 수 있습니다

 

추가로, Documentation UI에서 직접 API 호출이 가능하여 직관적인 디버깅이 가능하다는 점 또한 하나의 장점입니다

 

 

이 글에서 살펴봤다시피

 

Armeria에서 제공하는 Documentation Service는 

 

들어가는 공수 대비 Output이 괜찮은 편입니다

 

따라서, 한 번쯤 사용해 보는 것도 좋겠다고 추천드리며 이번 글을 마치겠습니다

 

 

 

예시 코드

GitHub - meeingjae/armeria-book-service: Armeria Restful Http Server