Spring Swagger(Open API)

Spring Swagger(Open API)

 

 

 

1. Swagger란?

스웨거는 협업을 위해 필요한 라이브러리이다.

 

스웨거가 나오기 전에는

서버 개발자가 어떤 API를 만들어서 나누어 주려면

API 스펙(URL, RequestParam, response 등)을 엑셀 파일 같은 곳에 직접 정리하고,

다른 사람들에게 나누어준 뒤에 수정해야 하는 일이 생기거나 하면 엑셀 파일을 열어서,

또 다시 수작업으로 전부 바꾸고 하면 너무 번거롭다.

 

이런 것들을 자동으로 문서화 시켜주기 위해 스웨거를 사용한다.

문서화 뿐만 아니라, 빌드, 테스트 케이스 작성도 가능하다던데

지금은 그냥 간단하게 문서화되는 것을 확인만 할 것이다.

 

근데 주의점이 있다.

스웨거가 springfox, springdoc 2가지가 있는데, springfox는 2020년에 개발이 멈췄다.

스프링 3버전대를 사용하는 중이면 springdoc를 사용해야 호환이 된다.

스프링 3버전대에 springfox를 사용하면 오류가 나는 부분들이 많아서 되도록 springdoc를 사용해주자.

어제 이거 직접 당해가지고 2시간 시원하게 날렸으니 부디 다른 사람들은 그러지 않기를 바란다.

 

이제 코드를 통해 알아보자.

 

 

 

2. 의존성 추가

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.6.0</version>
</dependency>

 

그리고 application.properties에 다음 코드 추가

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

스프링 부트 2.5에서 2.6으로 업데이트 되면서

 spring.mvc.pathmatch.matching-strategy 값이 ant_apth_matcher에서 path_pattern_parser로 변경되어서

swagger를 포함해서 몇몇 라이브러리에 오류가 발생할 수 있다고 한다.

그걸 해결해주는 코드라고 한다.

 

이제 http://localhost:8080/swagger-ui/index.html를 입력해서 화면을 확인해보자.

빈 화면이 나온다.

이제 내용물을 채워보자.

 

 

 

3. API 생성

@RestController
@RequestMapping(value = "example")
public class ExampleController {

    @GetMapping(value = "/")
    public String getExample() {
        return "example";
    }

    @PostMapping("/")
    public String postExample() {
        return null;
    }
}

대충 만들어봤다.

다시 화면을 봐보자.

뭔가 생겼다.

열어보자.

 

이렇게 생겼다.

지금 매개변수가 없어서 그런데 Try it out을 누르면 실험해볼 수도 있다고 한다.

 

 

 

4. 추가 설정

지금 화면에 나오는 것들은 전부 기본 속성에 따라 나오는 것이다.

직접 어노테이션을 사용해서 바꿔보자.

어노테이션이 너무 많아서 자주 쓰는 것들 위주로 다루겠다.

 

 

4 - 1. 어노테이션

@Tag

컨트롤러에 붙으며, 어떤 그룹에 속하는 지 알려준다.

 

@Operation

API에 대한 설명, 요약 등을 지정한다.

 

@Parameter

파라미터의 타입이나 입력에 관한 설명을 지정한다.

 

@ApiResponse

파라미터의 응답 구조를 나타낸다.

 

@Schema

입출력에 관한 데이터를 정의한다.(주로 DTO)

 

속성들도 많은데, 자주 쓰일 것들만 사용했다.

자세한 건 예시 코드를 보자.

 

 

4 - 2. 사용 예시

ExampleController

@Tag(name = "example", description = "예시용 API")
@RestController
@RequestMapping(value = "example")
public class ExampleController {

    @GetMapping(value = "/")
    @Operation(summary = "조회용 메서드", description = "뭔가를 조회함")
    @ApiResponse(responseCode = "200", description = "조회 성공함")
    @ApiResponse(responseCode = "400", description = "조회 실패함")
    public ExampleDTO getExample(
            @Parameter(description = "테스트용 파라미터")
            @RequestParam
            String ex1
    ) {
        return new ExampleDTO();
    }

    @PostMapping("/")
    @Operation(summary = "등록용 메서드", description = "뭔가를 등록함")
    @ApiResponse(responseCode = "200", description = "등록 성공함")
    @ApiResponse(responseCode = "400", description = "등록 실패함")
    public String postExample() {
        return null;
    }
}

 

ExampleTwoController

@Tag(name = "exampleTwo", description = "예시용2 API")
@RestController
@RequestMapping(value = "example")
public class ExampleTwoController {
    @GetMapping(value = "/")
    @Operation(summary = "조회용 메서드", description = "뭔가를 조회함")
    @ApiResponse(responseCode = "200", description = "조회 성공함")
    @ApiResponse(responseCode = "400", description = "조회 실패함")
    public String getExampleTwo(
            @Parameter(description = "테스트용 파라미터")
            @RequestParam
            String ex1
    ) {
        return "example";
    }
}

이건 그냥 @Tag 사용했을 때 겉에서 봤을 때 무슨 차이인지 보려고 간단하게 하나 만들었다.

 

ExampleDTO

@Data
@Schema(description = "예시용 DTO")
public class ExampleDTO {
    @Schema(description = "아이디")
    private String id;
    @Schema(description = "비밀번호")
    private String password;
}

 

이제 화면으로 확인해보자

 

 

4 - 3. 사용 결과

@Tag

2개로 구분되었다.

@Tag(name = "example", description = "예시용 API")
@Tag(name = "exampleTwo", description = "예시용2 API")

 

 

@Operation

간단한 설명이 생겼다.

@Operation(summary = "조회용 메서드", description = "뭔가를 조회함")

 

 

@ApiResponse

구분지어졌다.

@ApiResponse(responseCode = "200", description = "조회 성공함")
@ApiResponse(responseCode = "400", description = "조회 실패함")

 

@Parameter

파라미터 추가됨

@Parameter(description = "테스트용 파라미터")

 

 

@Schema

설명 추가됨

 

 

추가로, 맨 처음에 나왔던 화면도 바꿀 수 있다.

다음 코드 추가

SwaggerConfiguration

@Configuration
public class SwaggerConfiguration {

    private static final String API_NAME = "제목 적으면 되는 곳";
    private static final String API_VERSION = "버전 적는 곳";
    private static final String API_DESCRIPTION = "설명 적으면 되는 곳";


    @Bean
    public OpenAPI openAPIConfig() {
        return new OpenAPI()
                .info(new Info()
                        .title(API_NAME)
                        .description(API_DESCRIPTION)
                        .version(API_VERSION));
    }
}

 

화면

자기가 원하는 값을 지정하면 된다.

 

 

 

5. 최적화

지금 컨트롤러를 보면, 온갖 어노테이션이 붙어있어서 정신이 혼미해질 것 같다.

실제로는 어노테이션을 저거보다 더 많이 사용해야되니까 더 많아질 것이다.

이렇게 하지 말고, 스웨거용 인터페이스를 따로 만들어서 컨트롤러가 인터페이스를 상속받는 구조로 만들면

가독성과 스웨거의 편리함을 둘 다 챙길 수 있다.

 

ExampleControllerDoc 인터페이스 생성

@Tag(name = "example", description = "예시용 API")
public interface ExampleControllerDoc {
    @GetMapping(value = "/")
    @Operation(summary = "조회용 메서드", description = "뭔가를 조회함")
    @ApiResponse(responseCode = "200", description = "조회 성공함")
    @ApiResponse(responseCode = "400", description = "조회 실패함")
    public ExampleDTO getExample(
            @Parameter(description = "테스트용 파라미터")
            @RequestParam
            String ex1
    );

    @PostMapping("/")
    @Operation(summary = "등록용 메서드", description = "뭔가를 등록함")
    @ApiResponse(responseCode = "200", description = "등록 성공함")
    @ApiResponse(responseCode = "400", description = "등록 실패함")
    public String postExample();
}

 

ExampleController 변경

@RestController
@RequestMapping(value = "example")
public class ExampleController implements ExampleControllerDoc {

    @GetMapping(value = "/")
    public ExampleDTO getExample(String ex1) {
        return new ExampleDTO();
    }

    @PostMapping("/")
    public String postExample() {
        return null;
    }
}

컨트롤러가 깔끔해졌다.

실제로 화면 상으로도 똑같은 걸 확인해볼 수 있다.

http://localhost:8080/swagger-ui/index.html에서 확인해보자.