Swagger 를 통한 REST API 문서화

백엔드 개발자가 작성한 REST API 를 프론트엔드 개발자에게 문서화해서 넘겨줄때,

매번 일일이 문서화하여 작성하는 일은 매우 불편할 것이다

 

그래서 이런 단점을 개선하기위해 나온 것이 Swagger 이다

 

Swagger 는 백엔드 개발서버가 실행될때, 백엔드 서버내의 모든 API 를 탐색해서 알아서 문서화하여 UI 까지 제공한다

 

사용방법도 어렵지 않다

 

 

* 3.0 이상의 버전과 그 이하의 버전은 적용방법이 약간 다르다

여기서는 3.0 미만의 버전만 설명한다

또한 maven을 기준으로 설명되어 있다

(3.0 이상의 버전은 아래 링크 참조)

woowacourse.github.io/javable/post/2020-08-31-spring-swagger/

API 문서 자동화 - Swagger 팔아보겠습니다

 

 

- pom.xml

<properties>
    <springfox.version>2.9.2</springfox.version>
</properties>
 
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${springfox.version}</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${springfox.version}</version>
</dependency>

 

의존성 설치 이후에 아래와 같이 자바 설정 파일을 만들어준다.

 

- SwaggerConfiguration.java

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
 
    @Bean
    public Docket Api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                .apiInfo(getApiInfo());
    }
 
    private ApiInfo getApiInfo() {
        return new ApiInfoBuilder()
                .title("<Site Name> API")
                .version("<Site Version>")
                .description("API for <Site Name> Application")
                .contact(new Contact("<API Provider Name>", "<API Provider contact url>", "<API Provider email>"))
                .license("<License Name>")
                .build();
    }
}

1. Docket 은 Swagger 를 설정할수 있게 도와주는 클래스이다.

 - select() : ApiSelectorBuilder 를 생성해서 apis() 와 paths() 를 사용할 수 있게 한다

 - apis() : api 가 작성되어 있는 패키지를 지정한다

 - paths() : apis() 로 선택된 API 중 원하는 path 를 지정하고 문서화하는 역할을 한다

 

* apis() 와 paths() 내부에 전부 any() 로 쓴 것은 백엔드 서버 내에 API 가 많지 않다고 가정했기 때문이다

특정 api 의 카테고리만 하고 싶다면 PathSelectors.ant("/users/**") 이런식으로 할 수도 있다.

 

2. ApiInfo 는 그냥 이름에서도 알 수 있듯, API 정보를 지정하는 부분인데, 이 클래스에 대한 생성자 매개변수는 아래와 같다.

(위에선 builder pattern 으로 작성됨)

public ApiInfo(
    String title,
    String description,
    String version,
    String termsOfServiceUrl,
    Contact contact,
    String license,
    String licenseUrl,
    Collection<VendorExtension> vendorExtensions)

 

각각에 대한 내용은 아래 처럼 swagger ui 에 나타나게 된다.

 

출처 : https://woowacourse.github.io/javable/post/2020-08-31-spring-swagger/

 

 

 

- References)

1. woowacourse.github.io/javable/post/2020-08-31-spring-swagger/  

2. swagger.io/docs/