Swagger API 설정 방법, 실행

개요

Postman Team 사용이 4명 이상일 경우 해당 기간 동안만 무료로 사용할 수 있어서 방안을 찾던 중 방안 중 하나인 API 명세서 만들어주는 Swagger를 설정 방법과 사용법에 대해 작성하려고 한다.

Swagger란?

Swagger를 사용하면 @어노테이션 코드 몇 줄 추가하여 간단하게 API별로 문서화 및 API테스트 가능한 UI 까지 제공하여 문서 작성 시간을 극도로 단축하여 개발에 집중할 수 있다.

Swagger 버전

Swagger는 버전별로 차이가 있다.

Swagger 3.x.x 이후 부터 접속 url 변경 등 2.x.x 와 3.x.x 는 차이점이 있으며 해당 프로젝트는 Swagger 2.9.2 사용한다.

• 2.x.x : http://localhost:8080/swagger-ui.html
• 3.x.x : http://localhost:8080/swagger-ui/

Swagger 설정

• Gradle에 Swagger 의존성을 추가해준다.

//swagger
	implementation group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'
	implementation group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2'

• Swagger 버전 호환 이슈 해결
  1. org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException
  2. Caused by: java.lang.NullPointerException: null

Swagger 버전 호환 이슈로 위와 같은 오류가 발생했다.

해결법

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

application.yml이나 application.propertise에 위와 같은 코드를 작성한다.

• Swagger config class 생성

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket restAPI() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("j2kb.ponicon.scrap")) // 특정 패키지경로를 API문서화 한다.
                .paths(PathSelectors.any()) // apis중에서 특정 path조건 API만 문서화 하는 2차 필터
                .build()
                .groupName("API 1.0.0") // group별 명칭을 주어야 한다.
                .useDefaultResponseMessages(false); // 400,404,500 .. 표기를 ui에서 삭제한다.
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot REST API test")
                .version("v0.0.1")
                .description("스크랩 JPA swagger api 입니다.")
                .build();
    }
}

useDefaultResponseMessages(false)를 사용하면 아래와 같은 화면이 출력되지 않는다.

적용 전

적용 후

private ApiInfo apiInfo()는 아래와 같은 Swagger 화면을 작성하는 메서드이다.

• Swagger-ui 실행

현재 우리는 2.x.x 버전을 사용하므로 http://localhost:8081/swagger-ui.html

• API에 Swagger @Annotation 추가

@Api(tags = "카테고리와 관련된 API") -> class
@ApiOperation(value = "카테고리 조회 API", notes = "UserId를 RequestParam으로 받아서 categoryService.categories 후 카테고리를 조회하는 역할을 합니다. /category/all?id=") -> Method
@ApiParam(value = "User의 id 값", example = "2") -> parameter

• @Api tags : 해당하는 controller.java 에 대한 Title명칭 부여
• @ApiOperation value : API에 대한 요약하여 작성 notes : API에 대한 자세한 설명 작성
• @ApiParam value= 파라미터에 대한 설명 descriptionexample = 파라미터의 default 값이 있을 때 사용 required = true : 파라미터의 필수인지 표기 필수는 true, 아니면 false

위의 @Api 어노테이션을 통해 작성한 Swagger 화면

위의 @ApiOperation 어노테이션을 통해 작성한 Swagger 화면

위의 @ApiParam 어노테이션을 통해 작성한 Swagger 화면

Swagger 사용법

• 위의 사진의 오른쪽 상단에 보면 Try it out이 있다. Try it out을 클릭한다.

• 만약 Default값으로 값이 들어가 있다면 바로 Execute버튼을 클릭하면 실행이 된다. Default값 외의 다른 값으로 Test해보고 싶을 때는 다른 값을 넣어준다.

• 위의 파라미터 값을 넣어서 실행한 화면이다.

단점

Swagger 코드가 들어가서 코드가 길어보이고 지저분해 보인다.

 

참고 블로그

https://velog.io/@dkatlf900/swagger

Swagger API DOC 구축부터 실행까지