[Spring Boot] Swagger API Docs 작성하기 (SpringDoc, SpringBoot 3 버전)

 

 

 

이전에 Spring Boot 프로젝트에 Swagger를 연동해 본 적이 있었다.

최근 Spring Boot의 지원 버전이 3점대로 올라감과 동시에, 2점대에서 Swagger 사용 목적으로 많이 사용되는 SpringFox가 안타깝게도 제대로 지원되지 않는다.

3점대의 Spring Boot에서는 지원과 활동이 활발한 SpringDoc을 통해 Swagger 설정을 하는 것이 유리할 것이다.

 

 

2점대의 Spring에서 Swagger를 설정했던 방법은 다음 포스팅에 있다.

https://sjh9708.tistory.com/78

[SpringBoot] API 문서 생성 - Swagger 연동하기

 

 

---

의존성 

 

 

▶ build.gradle

plugins {
	id 'java'
	id 'org.springframework.boot' version '3.2.1'
	id 'io.spring.dependency-management' version '1.1.4'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'

java {
	sourceCompatibility = '17'
}

// ... 

dependencies {
	// ...
    
	//Swagger
	implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'


}

 

이번 프로젝트에서는 Spring 3.2.1버전을 사용하고, 이에 따라 Springdoc을 의존성으로 추가해주었다.

 

 

---

Swagger 설정

 

 

▶ application.yml

springdoc:
  swagger-ui:
    groups-order: DESC
    tags-sorter: alpha
    operations-sorter: method
    disable-swagger-default-url: true
    display-request-duration: true
    defaultModelsExpandDepth: 2
    defaultModelExpandDepth: 2
  api-docs:
    path: /api-docs
  show-actuator: true
  default-consumes-media-type: application/json
  default-produces-media-type: application/json
  writer-with-default-pretty-printer: true
  model-and-view-allowed: true
  paths-to-match:
    - /api/v1/**

 

application.yml 파일에 Springdoc 라이브러리의 Swagger에 대한 설정을 정의해준다.

 

paths-to-match: Swagger 문서를 생성할 API 경로를 지정한다.  /api/v1/로 시작하는 경로들을 대상으로 한다.

기타 설정들에 내용들은 Springdoc 공식 문서를 참조하는 것이 좋을 것이다.

 

 

 

 

▶ SwaggerConfig.java

@OpenAPIDefinition(
        info = @Info(
                title = "Example API Docs",
                description = "Description",
                version = "v1"
        )
)
@Configuration
public class SwaggerConfig {

    private static final String BEARER_TOKEN_PREFIX = "Bearer";

    @Bean
    public OpenAPI openAPI() {
        String securityJwtName = "JWT";
        SecurityRequirement securityRequirement = new SecurityRequirement().addList(securityJwtName);
        Components components = new Components()
                .addSecuritySchemes(securityJwtName, new SecurityScheme()
                        .name(securityJwtName)
                        .type(SecurityScheme.Type.HTTP)
                        .scheme(BEARER_TOKEN_PREFIX)
                        .bearerFormat(securityJwtName));

        return new OpenAPI()
                .addSecurityItem(securityRequirement)
                .components(components);
    }

}

 

Swagger의 설정에 대해서 Configuration 클래스를 작성해주었다.

@OpenAPIDefinition에 문서에 대한 스펙사항을 작성해 주면서, Swagger Configuration으로서 사용되게 한다.

 

openAPI 메서드는 Swagger 문서의 전체적인 설정을 담고 있다.

 

내부에 openAPI() 빈의 설정에는 Security에 대한 설정을 해 주었다. 해당 설정은 JWT 인증을 사용할 경우를 가정하여 만든 것으로, JWT 인증에 사용될 Swagger 보안 스키마 규칙과 요구사항을 정의하였다. 최종적으로 openAPI 메서드에서는 보안 요구사항과 보안 스키마를 포함한 OpenAPI 객체를 생성하여 반환한다.

 

BEARER_TOKEN_PREFIX : JWT 토큰을 사용하는 보안 스키마의 접두사 규칙 설정에 사용되었다. "Bearer" Prefix를 사용하여 JWT를 전달한다고 설정하였다.

 

 

 

 

 

 

 

---

Swagger API 스펙 작성

 

@Tag(name = "Example", description = "Example API")
@RestController
@RequiredArgsConstructor
@RequestMapping("/api/v1/example")
public class ExampleApiController {

    @PostMapping("/{pathValue}")
    @Operation(summary = "Example API Summary", description = "Your description")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "Success",
                    content = {@Content(schema = @Schema(implementation = BasicResponseDto.class))}),
            @ApiResponse(responseCode = "404", description = "Not Found"),
    })
    public BasicResponseDto exampleAPI(
            //Path Parameter
            @PathVariable
            @Schema(description = "Path Value", example = "1")
            Long pathValue,

            //Query Parameter
            @Parameter(name = "paramValue", description = "Parameter Value", example = "3", required = true)
            @RequestParam final Long paramValue,

            //Request Body
            @RequestBody @Valid MemberJoinRequestDto requestBody
    ) {
        String s = String.format("PathValue = %d , ParamValue = %s, Request Email : %s", pathValue, paramValue, requestBody.getEmail());
        BasicResponseDto response = new BasicResponseDto(true, "Example API Success",  s);
        return response;
    }




}

 

SpringFox에서도 Annotation을 통한 Swagger 문서화를 제공했었는데, SpringDoc도 유사하다. 다음은 Controller 단의 API를 문서화하는 예시이다.

@Tag는 해당 컨트롤러에 대한 설명을 정의한다.

@Operation에서는 각각의 API에 대한 설명을 정의한다.

@ApiResponse에서는 각각의 응답 코드에 따른 케이스를 설명하고 있다. 응답 성공 시 BasicResponseDto의 형태로 반환함을 알리고 있다.

 

API의 Request의 Input으로 사용되는 Path Parameter, Query Parater, Request Body에 대해서도 위의 예시처럼 작성할 수 있다.

 

 

 

---

 

Swagger DTO 스펙 작성

 

@Data
@AllArgsConstructor
@Schema(title = "MEM_REQ_01 : 회원가입 요청 DTO")
public class MemberJoinRequestDto {

    @NotBlank(message = "사용자 이메일을 입력해주세요.")
    @Email(message = "이메일 형식에 맞지 않습니다.")
    @Schema(description = "사용자 이메일", example = "testtest@gmail.com")
    private String email;

    @NotBlank(message = "사용자 이름을 입력해주세요.")
    @Size(min = 3, max = 15, message = "사용자 이름은 15글자 이하로 입력해야 합니다.")
    @Schema(description = "사용자 이름", example = "John Doe")
    private String name;

    @NotBlank
    @Schema(description = "비밀번호", example = "test123!")
    @Pattern(regexp="(?=.*[0-9])(?=.*[a-zA-Z])(?=.*\\W)(?=\\S+$).{8,20}",
            message = "비밀번호는 영문 대,소문자와 숫자, 특수기호가 적어도 1개 이상씩 포함된 8자 ~ 20자의 비밀번호여야 합니다.")
    private String password;
}

 

API의 Input과 Output으로 사용되는 DTO에 대한 문서 스펙또한 Annotation을 통해 정의할 수 있다.

@Schema는 해당 필드에 대한 설명을 작성하게 되며, @NotBlank, @Size 등의 Spring Validate Annotation은 자동으로 문서 스펙에 반영되게 된다.

 

@Data
@AllArgsConstructor
public class BasicResponseDto<T> {

    @Schema(description = "성공 여부", example = "true")
    private boolean success;

    @Schema(description = "응답 메시지", example = "Success")
    private String message;

    @Schema(description = "응답 데이터", example = "Any Data")
    private T data;
}

 

마찬가지로 응답에 대한 Response DTO도 한번 작성해 보았다.

 

 

 

 

 

---

Swagger 문서 결과 확인

 

Swagger 문서의 디폴트 경로는 http://IP:PORT/swagger-ui/index.html이다.

 

 

 

 

 

 

---

References

 

https://hogwart-scholars.tistory.com/entry/Spring-Boot-SpringDoc%EA%B3%BC-Swagger%EB%A5%BC-%EC%9D%B4%EC%9A%A9%ED%95%B4-API-%EB%AC%B8%EC%84%9C%ED%99%94-%EC%9E%90%EB%8F%99%ED%99%94%ED%95%98%EA%B8%B0

[Spring Boot 3] SpringDoc과 Swagger를 이용해 API 문서화 자동화하기