Spring swagger 3 사용방법(springdoc-openapi-ui)

Springdoc OpenAPI UI

스프링 부트에서 'springdoc-openapi-ui'를 사용하여 swagger3를 적용하는 방법에 대해서 살펴보겠습니다.

'springfox-swagger-ui', 'springfox-swagger2'를 사용하는 방법과는 다른 방법이며, 오로지 'springdoc-openapi-ui' 하나만 사용하여 swagger를 설정하는 방법입니다.

 

스웨거를 적용하는 과정에서 실행 시 오류가 발생하는 경우는 대부분 spring boot의 버전과 springdoc의 버전 차이가 원인일 수 있는데요.

저 같은 경우는 테스트 시 spring boot 2.7.0 버전에 springdoc 1.5.2 버전으로 실행했을 때, 실행 자체에서 BeanCreationException 오류가 발생했었는데, springdoc의 낮은 버전으로 인해 오류가 나는 것 같아 버전을 올리니 정상적으로 실행되었습니다.

(2022년 5월 현재 Springdoc OpenAPI UI의 최신 버전은 1.6.9 버전입니다.)

 

 

---

 

 

Swagger란 무엇인지 간단하게,

Swagger가 무엇인지 알기 위해서는 먼저 'Open Api Specification'에 대해서 알아야 하는데요.

Open Api Specification(OAS)는 RESTful 웹 서비스를 접할 때, 직접 소스 코드나 문서를 보지 않고도 이해할 수 있도록 시각화하기 위한 인터페이스 파일의 사양을 이야기합니다.

(Specification 단어 뜻 그대로 Open Api의 사양입니다.)

그리고 Swagger는 Open Api Specification을 위한 프레임워크인데요.

 

조금 정리해보면 RESTful 웹 서비스를 소스 코드나 문서를 보지 않고 이해할 수 있도록 시각화하기 위해 Swagger를 사용하고, Swagger를 통해 API의 사용 방법을 사용자에게 알려주는 것이라고 할 수 있습니다.

 

 

---

 

 

Pom.xml 의존성 추가

<!-- https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.7</version>
</dependency>

// https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui
implementation group: 'org.springdoc', name: 'springdoc-openapi-ui', version: '1.6.7'

Maven 또는 Gradle 의존성 추가입니다.

 

 

.properties 파일 설정

# swaggerdoc
springdoc.version=v1.0.0
springdoc.packages-to-scan=com.example.swagger3test
springdoc.swagger-ui.path=/api-docs
springdoc.swagger-ui.tags-sorter=alpha
springdoc.swagger-ui.operations-sorter=alpha
springdoc.api-docs.path=/api-docs/json
springdoc.api-docs.groups.enabled=true
springdoc.cache.disabled=true
springdoc.default-consumes-media-type=application/json;charset=UTF-8
springdoc.default-produces-media-type=application/json;charset=UTF-8

이어서 .properties 파일에 다음과 같은 설정을 할 수 있는데요.

 

'.version'의 경우 이어서 나오는 내용인 OpenAPI bean 등록 시 사용되며, '.packages-to-scan'은 swagger 적용을 위해 스캔할 패키지를 지정하는 것입니다.

그리고 중요한 것이 '.swagger-ui.path'인데요. swagger-ui를 연결할 주소를 지정할 수 있으며, 지정하지 않았을 경우에는 localhost:{port}/swagger-ui/index.html의 경로로 접근할 수 있습니다.

(/api-docs를 경로를 지정했기 때문에 실행 후 해당 경로로 접근하면 Swagger가 적용된 것을 볼 수 있습니다.)

 

나머지 아래 설정들은 정렬 방식, 캐시, consumes, produces 타입에 관련된 것입니다.

(기본적인 옵션들이며, 더 자세한 옵션들과 내용들은 포스팅 맨 하단 공식 문서를 참고 부탁드리겠습니다.)

 

 

---

 

 

OpenAPI bean 등록

@Configuration
public class OpenApiConfig {

  @Bean
  public OpenAPI openAPI(@Value("${springdoc.version}") String springdocVersion) {
    Info info = new Info()
        .title("타이틀 입력")
        .version(springdocVersion)
        .description("API에 대한 설명 부분");

    return new OpenAPI()
        .components(new Components())
        .info(info);
  }
}

이어서 OpenAPI bean 등록을 위해 Configuration 클래스를 생성합니다.

OpenAPI bean에 관한 내용 역시 가장 기본적인 title, version, description에 대한 것만 담았으며, @Value 어노테이션을 통해 .properties에서 등록한 springdoc.version 값을 가지고 오는 것을 확인할 수 있습니다.

 

 

title, version, description 적용

 

 

---

 

 

@Controller 설정

@Tag(name = "인증", description = "인증 관련 api 입니다.")
@RestController
@RequestMapping("/api/auth")
public class AuthController {

    @Operation(summary = "로그인 메서드", description = "로그인 메서드입니다.")
    @ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "successful operation", content = @Content(schema = @Schema(implementation = LoginResponse.class))),
        @ApiResponse(responseCode = "400", description = "bad request operation", content = @Content(schema = @Schema(implementation = LoginResponse.class)))
    })
    @PostMapping(value = "login")
    public ResponseEntity<LoginResponse> login(LoginRequest loginRequest) {
        LoginResponse loginResponse = new LoginResponse("accessTokenValue", "refreshTokenValue");
        return ResponseEntity.ok().body(loginResponse);
    }
}

@Tag

api 그룹 설정을 위한 어노테이션입니다.

name 속성으로 태그의 이름을 설정할 수 있고, description 속성으로 태그에 대한 설명을 추가할 수 있습니다.

@Tag에 설정된 name이 같은 것 끼리 하나의 api 그룹으로 묶게 됩니다.

 

@Operation

api 상세 정보 설정을 위한 어노테이션입니다.

summary 속성으로 api에 대한 간략한 설명, description 속성으로 api에 대한 상세 설명을 추가할 수 있으며, responses, parameters 속성 등을 추가로 적용할 수 있습니다.

 

@ApiResponses

바로 아래에서 설명하는 여러 개의 @ApiResponse를 묶기 위한 어노테이션입니다.

 

@ApiResponse

api의 response 설정을 위한 어노테이션입니다.

responseCode 속성으로 http 상태 코드를 설정할 수 있고, description으로 response에 대한 설명을 추가할 수 있습니다. @ApiResponse 설정을 통해 응답 결과로 나올 수 있는 response 구조를 미리 확인할 수 있게 됩니다. 

api 조회 성공 및 실패 시 발생될 상태 코드 및 Response 구조를 설정하고자 할 때 유용하게 사용될 수 있습니다.

(implementation에는 responseBody로 제공될 클래스 타입만 설정할 수 있습니다.)

 

@Parameter

예시에는 없지만 해당 어노테이션은 api parameter 설정을 위한 어노테이션입니다.

name으로 파라미터의 이름, description으로 설명, in으로 파라미터의 위치를 설정할 수 있습니다.

 

 

@Tag @Operation 설정

 

 

@ApiResponse 설정

 

 

---

 

 

Request, Response 객체 설정

@Getter
public static class LoginRequest {
    @Schema(description = "아이디", defaultValue = "testId")
    public String id;
    @Schema(description = "비밀번호", defaultValue = "testPassword")
    public String password;
}
  
@Getter
@AllArgsConstructor
public static class LoginResponse {
    @Schema(description = "엑세스 토큰")
    private String accessToken;
    @Schema(description = "리프레시 토큰")
    private String refreshToken;
}

@Schema

Request, Response 객체에 대한 설정을 위한 어노테이션입니다.

description으로 설명을 추가할 수 있고, defaultValue으로 기본적으로 사용할 값을 설정할 수 있으며, example을 통해 예시를 설정할 수도 있습니다.

 

 

여기까지가 'springdoc-openapi-ui'를 사용한 기본적인 swagger3 설정 방법입니다.

정말 기본이 되는 어노테이션과 옵션들만 적용했기 때문에 추가적으로 필요한 부분은 아래 공식 문서를 참고하여 추가로 적용해주시면 될 것 같습니다.

 

 

 

< 공식 문서 >

OpenAPI 3 Library for spring-boot

 

< 참고 자료 >

[Spring Boot Tutorial] 15. Open API 3.0 + Swagger v3 상세설정

 

 

OpenAPI 란? (feat. Swagger)