API 문서화

API를 개발 하고 나면 문서화를 해야 한다.

문서화는 작업 했던 것을 기록하는것 뿐만 아니라 함께 작업하는 개발자들에게 공유하는 내용이기도 하다.

회사마다, 사람마다 API 문서화 방식이 다르기 때문에 잘 맞는 것을 찾아서 사용하면 된다.

특히 공유가 되는 내용이라면 코드의 수정이 생겼을 경우 API 문서 역시 수정을 해줘야 한다.

예를들어, Parameter가 String 에서 Integer로 바꼈을 경우에 API 문서 역시 수정을 해야 한다.

하지만 생각보다 API문서의 수정작업을 잊는 일이 많이 발생한다.

그래서 이 책에선 이런 문제를 해결하기 위한 여러가지 프로젝트 중에서 스웨거2를 소개한다.

스웨거 2를 스프링 부트와 같이 사용하기

의존성 추가

스웨거2를 스프링 부트에서 사용하려면 아래 2개의 의존성을 추가해야 한다.

<!--Swagger2-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.2.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.2.2</version>
</dependency>

라고 책에 나와 있지만 이후 작업을 위해서는 하나가 더 필요하다.

<!--Maven Model-->
<dependency>
    <groupId>org.apache.maven</groupId>
    <artifactId>maven-model</artifactId>
    <version>2.2.0</version>
</dependency>

애플케이션이 시작될 때 스웨거 라이브러리에 의해 API 문서가 소스코드로부터 자동으로 생성된다고 한다.

이 처리는 메인 클래스에 선언된 Docket 빈에 의해 조절 되는데 Docket을 사용하기 위해서는 maven-model dependency 가 필요하다.

Docket Bean 등록

그리고 다음과 같이 SwaggerConfig를 @Configuration, @EnableSwagger2 애노테이션을 추가하여 등록한다.

@Configuration
@EnableSwagger2
public class SwaggerConfig {                                    
    @Bean
    public Docket api() { 
        return new Docket(DocumentationType.SWAGGER_2)
          .select()                                  
          .apis(RequestHandlerSelectors.any())
          .paths(PathSelectors.any())
          .build();                                           
    }
}

Docket Bean을 추가했다.

select() 메소드는 ApiSelectorBuilder를 리턴하는데 이것은 스웨거에 의해 노출되는 endpoint를 제어하는 방법을 제공한다.

RequestHandlersSelectors.any(), PathSelectors.any() 로 지정을 하면 전체 API가 스웨거를 통해 문서화 된다.

실행 화면

서버를 실행한다.

그리고 나서 http://localhost:8080/swagger-ui.html 로 이동하면 swagger 화면이 뜰 것이다.

특정 패키지에 있는 API만 문서화 하고 싶다면 아래 코드처럼 설정하면 된다.

.apis(RequestHandlerSelectors.basePackage("com.midasit.msa.controller"))

basic-error-controller 가 사라진 것을 확인할 수 있다.

특정 메소드만 문서화 하고 싶담녀 아래 코드처럼 설정하면 된다.

.apis(RequestHandlerSelectors.basePackage("com.midasit.msa.controller"))
.paths(PathSelectors.ant("/user/name"))

user-controller의 경로가 '/user/name' 만 문서화 된 것을 확인할 수 있다.

API 항목을 클릭해서 자세하게 확인해 보도록 하자.

'/user/name' 을 클릭하면 위의 이미지 처럼 상세 화면이 나온다.

파라미터를 입력할 수 있고, Try it out! 을 통해 요청을 보낼 수 있다. 그리 하면 요청정보와 응답정보를 확인할 수 있다.

매우 간단하면서도 매우 편리하다.

더 자세한 내용은 https://www.baeldung.com/swagger-2-documentation-for-spring-rest-api 이곳을 참고하면 된다.