Spring Boot Swagger 3 사용하기 feat. springdoc

Swagger 

Swagger란 서버로 요청되는 URL 리스트를 HTML화면으로 문서화 및 테스트 할 수 있는 라이브러리이다.

간단하게 설명하면 Swagger는 API Spec 문서이다.

API를 엑셀이나 가이드 문서를 통해 관리하는 방법은 주기적인 업데이트가 필요하기 때문에 관리가 쉽지 않고 시간이 오래 걸린다.

그래서 Swagger를 사용해 API Spec 문서를 자동화해주어 간편하게 API문서를 관리하면서 테스트할 수 있다.

 

선발주자로 springfox가 시작이 되었고, 후발 주자로 springdoc-openapi가 나왔다.
그러나 springfox는 2020년 이후 업데이트를 수행하고 있지 않으며, springdoc-openapi는 현재까지 업데이트를 진행하고 있다.

따라서 본 문서는 springdoc를 사용한다.

build.gradle

...

dependencies {
	...
	/*
	Springdoc OpenAPI UI
	 */
	implementation 'org.springdoc:springdoc-openapi-ui:1.6.9'
}

...

Bean 등록

@Configuration
public class Swagger2Config {

    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("v1-definition")
                .pathsToMatch("/api/**")
                .build();
    }
    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI().addServersItem(new Server().url("/"))
        	//SecurityScheme 등록
                .components(new Components()
                        .addSecuritySchemes("bearer-key",
                                new SecurityScheme()
                                .type(SecurityScheme.Type.HTTP)// HTTP 방식
                                .scheme("bearer")
                                .bearerFormat("JWT")// 토큰 형식을 지정하는 임의의 문자(Optional)))
                .info(new Info().title("title")
                        .description("description")
                        .version("v0.0.1"));
    }
}

• GroupedOpenApi 설정을 하면 그룹 설정된 api 들만 문서에 노출시킬 수 있게 해준다. 즉, /api/** uri에 대해서만 문서 노출 된다
• OpenAPI().info() 는 문서에 대한 설명이다
• 기본적으로 OpenAPI 3에서는 API 호출 시 인증에 대한 처리를 위해 Security Scheme를 지원하는데 이 Security Scheme를 통해 설정을 진행한다.  SecurityScheme 를 통해서 전역 JWT 인증 설정을 등록한다. 위와 같이 설정하고 SwaggerUI를 실행해보면 우측 상단에 Authorize 버튼이 표시되고 전역 인증 설정을 할 수 있다.

 

@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 속성으로 태그에 대한 설명을 추가할 수 있다.

 

@Operation

api 상세 정보 설정을 위한 어노테이션

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

 

@ApiResponses

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

 

@ApiResponse

api의 response 설정을 위한 어노테이션

responseCode 속성으로 http 상태 코드를 설정할 수 있고, description으로 response에 대한 설명을 추가할 수 있다.

 

@Operation(security = { @SecurityRequirement(name = "bearer-key") }, summary = "비밀번호 변경")
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "successful operation"),
            @ApiResponse(responseCode = "1003", description = "Password Not Match", content = @Content(schema = @Schema(implementation = CommonResponse.class)))
    })
    @PatchMapping(value ="/user/changepw")
    public SingleResponse<String> changeUserPassword(@RequestBody PasswordDto passwordDto){
        return responseService.getSingleResponse(userService.updatePassword(passwordDto));
    }

JWT 인증이 필요한 method에는 @Operation(security = { @SecurityRequirement(name = "bearer-key") } 를 추가해준다.

 

Swagger Annotation

태그	속성	설명
@Tag		Controller에 대한 설명을 명시하는 어노테이션
@Tag	name	API 그룹의 이름을 지정하는 속성
@Tag	description	API 그룹의 설명을 지정하는 속성
@Operation		API 그룹 내에 각각의 API를 명시하는 어노테이션
@Operation	summary	API에 대한 간략한 설명을 지정하는 속성
@Operation	description	API에 대한 상세 설명을 지정하는 속성
@Operation	response	API에 대한 응답을 지정하는 속성
@Operation	parameter	API에 대한 파라미터를 지정하는 속성
@Schema		모델에 대한 설명을 명시하는 어노테이션
@Schema	description	모델 자체 혹은 컬럼에 대한 설명을 하는 속성

 

 

 

출처

• https://adjh54.tistory.com/72
• https://happy-jjang-a.tistory.com/165
• https://wildeveloperetrain.tistory.com/156