Swagger - 프로젝트 문서화 하기

새하얗게 까먹어버렸기때문에

블로그에 박제해 본다

 

 

1. Swagger 라이브러리 추가

    implementation 'io.springfox:springfox-boot-starter:3.0.0'
    implementation 'io.springfox:springfox-swagger-ui:3.0.0'

2. application.yml에 설정 추가

 => 스프링MVC와 Swagger를 매칭해 주기 위함

  spring:
    mvc:
      pathmatch:
        matching-strategy: ant_path_matcher

3. Swagger 설정파일 추가

@Configuration
@EnableSwagger2
public class SwaggerConfig {

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

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("title")
                .description("description")
                .version("1.0")
                .build();
    }
}

4. 서버 실행 후 http://localhost:8080/swagger-ui/index.html 주소에서 swagger페이지 확인가능

 

 

 

 

 

 

Swagger페이지 커스텀하기

1. 단순 Error API없애기 

API목록중에 내가 만들지않은 Error API가 있을것이다. 그것을 안보이게 하고싶으면 아래의 내용을 참고한다.

- Swagger 설정파일에서 apis부분을 any()가 아닌 내 프로젝트명으로 바꿔준다(자바 아래의 패키지명)

  (error api는 내 프로젝트가아닌 spring단에서 만들어진 api이기때문에, 내 프로젝트에서 만들어진것만 쓰겠다는 의미)

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.emma_dev.ohguohgu"))
                .paths(PathSelectors.any())
                .build().apiInfo(apiInfo());
    }

 

 

2. 특정 경로의 API만 가져오고 싶은경우

- path부분에 any()가 아닌 ant()메서드를 사용하여 원하는 경로만 보이게 설정 가능

- 나만 보고싶은 api가 있는경우 설정값을 다르게하여 노출이 안되게 할 수 있다.

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.emma_dev.ohguohgu"))
                .paths(PathSelectors.ant("/admin/**"))
                .build().apiInfo(apiInfo());
    }

 

 

3. 각 API에 부가설명 붙이기

각 API 맨 오른쪽에 회색글씨로 API메서드 명이 써있는데, 이 부분을 API에 대한 설명으로 교체할 수 있다

부가설명 없음

부가설명있음(편안)

API에 @ApiOperation을 추가하여 부가설명을 붙일 수 있다.

 

아래와같이 각 API명과, 추가 설명을 붙이고싶다면, @ApiOperation 어노테이션에 notes키워드를 추가해주면 된다

이런식으로 구현 못해놓고 얼렁뚱땅 넘어가면 안된다(ㅠㅠ)

 

4. 파라미터로 넘어오는 인자에 대한 설명을 붙이고 싶을때

- 입력해줘야하는 인자의 형식이라던가 설명이 필요할때는 해당 파라미터앞에 @ApiParam어노테이션을 추가하여 value를 입력해준다.