Swag 넘치게 소통해보자! Swagger in SpringBoot 3.x 정복 (SpringFox, SpringDoc, API 문서 자동화하는 방법)

오랜만에 포스팅하는 이유는 한동안 별 탈 없이 프로젝트를 이어가고 있기 때문에.. 새롭게 무언가를 알아가거나 복습하는 일이 적었습니다..^^ 오늘은 Swaager 사용 도중에 궁금한 점이 많아지면서 조사한 내용들을 정리한 내용을 포스팅해보려 합니다.

---

Swagger 등장 전과 후 차이는?

Swagger가 세상에 등장하기 전, 개발자 간 소통 방식은 단순하게 백엔드 개발자가 URL 및 Request, Response를 직접 문서화해서 프론트엔드 개발자에게 전달하는 방식을 사용했습니다.

 

따라서 기능 구현을 위한 API 명세 및 요구사항이 있다고 가정했을 때, 각 개발자 간의 필연적인 책임이 따릅니다.  

• 백엔드 개발자는 API 구현에 있어서 어떠한 실수가 없어야 합니다.
• 백엔드 개발자는 기능 요구사항을 완벽히 이해해야 합니다.
• 프론트엔드 개발자는 기능 구현에 있어서 어떠한 실수가 없어야 합니다.
• 프론트엔드 개발자는 기능 요구사항을 완벽히 이해해야 합니다.

단순한 반복 작업인 만큼 생산성 측면에서는 다소 비효율적입니다. 이로 인해 여러 방면으로 불편함이 야기됩니다.

• 백엔드 개발자가 API 문서를 일일이 작성하는 번거로움
• API가 변경되면서 비일관적인 문서를 다시 수정해야 하는 번거로움
• 수기 작성으로 인한 휴먼에러 발생으로 개발자 간의 의사소통이 어려움
• 프론트엔드 개발자가 Postman, cURL로 직접 URL 및 Request 작성하여 API를 테스트해야 하는 번거로움

위와 같은 번거로움을 해결하기 위해 등장한 Swagger는 OAS(Open Api Specification)를 위한 오픈소스 프레임워크입니다. 사용하면 얻을 수 있는 장점이 있습니다.

• API 문서를 생성할 때, 개발자가 문서를 작성하지 않아도 되므로 개발 시간 단축
• Swagger UI를 이용하면 API를 쉽게 테스트할 수 있으며, API 호출 시 전달해야 할 파라미터를 확인할 수 있음
• Swagger를 사용하면 API 버전 관리가 용이해지고 다양한 API 문서를 통합할 수 있음 
• Spring Boot에서 Swagger를 사용하면 API 문서를 생성하는 데 필요한 코드를 직접 작성하지 않아도 되므로 개발자는 API 개발에 집중할 수 있음

---

Swagger를 다루는 두 가지 방법

1) YAML

Swagger를 구성하는 방법 중 첫 번째는 YAML파일을 사용하게 된다면 Swagger UI를 위한 서버를 따로 두고, Swagger에서 API 요청을 하면 그 요청을 해당 서버로 전달하게 됩니다. 반면 Spring Framework에서 구성 시 서버 자체가 Swagger 겸 백엔드 서버가 돼서, 요청 및 응답을 처리하게 됩니다.

 

이러한 구조를 따르면 YAML 파일을 이해하고 수정하기 쉬워지고, 명확한 아키텍처를 가질 수 있어서 개발자뿐만 아니라 기획자도 쉽게 이해할 수 있습니다. YAML 파일을 통해 구성하는 방법은 출처 원글을 통해 자세한 내용을 확인할 수 있습니다.

 

2) Spring Framework에서 구성

YAML파일로 구성하는 것과 다르게 각 Spring Framework 환경에서 동작하는 서버 내의 Swagger를 사용함으로써 각 서버의 API 명세를 확인할 수 있도록 구성하는 방법입니다. 설정과 관련된 어노테이션과 함수들이 잘 나와있어 적용하는 방법은 쉽지만, 코드 내에 작성을 하다 보니 소스 코드의 가독성이 저하된다는 단점이 있습니다.

---

Swagger 사용을 돕는 Tool & Library

1) Tool

1. Swagger Codegen

Codegen은 server stubs client SDKs를 생성할 수 있게 해 줍니다. 즉, Swagger에서 정의한 설계대로 개발을 진행할 수 있도록 합니다. 모든 언어를 지원하고 있지는 않습니다.

 

2. Swagger Editor

Swagger Editor는 Swagger를 온라인에서 작성할 수 있는 것이 특징입니다. Cloud 환경에서 작업할 수도 있고, Editor를 다운로드하여서 사용할 수도 있습니다. Docker를 통해 이미지로 제공하고 있습니다.

 

3. Swagger UI

Swagger의 표준에 맞춰 UI를 작성해 주는 에디터입니다.

 

2) Library

Swagger를 Spring 환경에서 쉽게 사용할 수 있도록 도와주는 라이브러리가 있습니다.

 

1. Springfox

Springfox Swagger의 경우 3.00 버전을 마지막으로 업데이트가 중단되어서 잘 사용하지 않는 추세라고 합니다. (Maven Repository 기준 2020년 7월 마지막 업데이트)

 

2. SpringDoc

SpringFox와 기능은 동일하지만 Spring WebFlux (논 블록킹 비동기 방식의 웹 개발)을 지원합니다. 또한, 그룹 간 API 정렬이 가능하다는 장점이 있습니다.

Springfox Swagger의 경우 2020년 7월에 업데이트 이후 후속 업데이트가 없습니다. 이후 나온 기능들에 대응이 안 되는 경우가 있어서 SpringDoc를 자주 사용합니다. 게다가 SpringBoot 3 환경에서 SpringFox는 사용이 불가능하다고 합니다. 

반응형

---

Swagger 사용 방법

SpringBoot에서 Swagger 설정하기

설정에 앞서 저는 SpringBoot 3.0.3 버전에서 적용했습니다. 아래 의존성을 추가하여 Swagger를 사용할 수 있도록 해줍니다.

implementation 'org.springdoc:springdoc-openapi-starter-common:2.0.2'

 

위 설정만으로도 현재 로컬에서도 Swagger 문서가 생성됩니다. 

http://localhost:8080/swagger/index.html

 

Swagger API 문서 관련 설정들을 제어할 수 있도록 SwaggerConfig 파일을 추가합니다. 

@Configuration
public class SwaggerConfig {

    private String version = "1.0.0";

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .components(new Components())
                .info(apiInfo());
    }
 
    private Info apiInfo() {
        return new Info()
                .title("제목")
                .description("설명")
                .version(version);
    }
}

 

또한 Swagger를 제어할 수 있는 yaml 파일을 추가해 줍니다. packages-to-scan 속성에 Swagger를 사용하기 위한 Controller가 있는 패키지 경로를 지정하면 자동으로 Swagger 문서에 등록됩니다. 등록을 원치 않는 컨트롤러에 @Hidden 어노테이션을 사용하여 제외할 수 있습니다. 각 속성에 대해서 더 알고 싶으시면 공식 문서를 확인해 주세요. (https://springdoc.org/#properties)

springdoc:
  packages-to-scan: com.example.swagger.web
  default-consumes-media-type: application/json;charset=UTF-8
  default-produces-media-type: application/json;charset=UTF-8
  swagger-ui:
    path: /
    disable-swagger-default-url: true
    display-request-duration: true
    operations-sorter: alpha

 

이제 Swagger 문서에 등록할 Controller 파일을 수정해서 Swagger 문서를 등록할 수 있습니다. SpringBoot 3 버전과 2 버전에서 어노테이션 차이가 있어 먼저 짚고 넘어가 보겠습니다.

@Api → @Tag
@ApiIgnore → @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden
@ApiImplicitParam → @Parameter
@ApiImplicitParams → @Parameters
@ApiModel → @Schema
@ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY)
@ApiModelProperty → @Schema
@ApiOperation(value = "foo", notes = "bar") → @Operation(summary = "foo", description = "bar")
@ApiParam → @Parameter
@ApiResponse(code = 404, message = "foo") → @ApiResponse(responseCode = "404", description = "foo")

 

아래와 같이 예제 API를 작성해 보았습니다.

    @GetMapping("/example/{id}")
    @Operation(summary = "조회 예제", description  = "조회한다", responses = {
    	@ApiResponse(responseCode = "200", 
            	      description = "조회 성공", 
                          content = @Content(array = @ArraySchema(schema = @Schema(implementation = exampleResource.class))))
    })
    @Parameter(name = "id", description = "예제 파라미터", in = ParameterIn.PATH)
    public List<CafeResource> search(@PathVariable("id") Long id) {
		...
    }
    
    @Hidden
    @GetMapping("/hidden")
    public String hidden() {
        return "Swagger에 등록되지 않는 API";
    }