Spring Boot 스웨거(Swagger UI) 적용

Swagger UI

• 프론트엔드와 백엔드간의 협업에 사용되는 툴이다.
• API를 시각화하는 코드가 자동으로 생성되게 해준다.
• RestDocs와 달리 스웨거 웹페이지에서 API를 실행해볼 수 있다.
• API 명세서를 직접 작성할 필요가 없어져 API 명세서 유지보수가 쉬워진다.

스웨거 웹페이지 주소

1. 2.x.x 버전 : localhost:8080/swagger-ui.html
2. 3.x.x 버전 : localhost:8080/swagger-ui/index.html

의존성 : implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.7.0'

 

config 설정

@Configuration
public class SwaggerConfig {

    // 모든 열거형이 별도의 스키마로 추출되어 components 섹션에 정의된다.
    static {
        io.swagger.v3.core.jackson.ModelResolver.enumsAsRef = true;
    }
	
    // api 버전별로 api를 나눌 수 있게 해주는 설정
    @Bean
    public GroupedOpenApi v1OpenAPI() {
        return GroupedOpenApi.builder()
                .group("v1") // 그룹의 이름을 설정
                .pathsToMatch("/api/v1/**") // 이 그룹에 들어갈 api를 설정
                .addOpenApiCustomizer(openApi -> openApi.info(v1Info())) // OpenApi 설정 추가
                .build();
    }

    private Info v1Info() {
        return new Info()
                .title("Study With Me API") // 제목 설정
                .version("1.0") // 버전 설정
                .description("API version 1 documentation"); // 설명 설정
    }
    
    /* 그룹별로 안 나눌 시에 OpenApi 설정
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI().info(apiInfo());
    }
    */
}

 

yml 설정

springdoc:
  swagger-ui:
    operations-sorter: method // HTTP 메소드에 따라 정렬

 

OpenApi가 아닌 GroupedOpenApi를 설정하면 사진 상단에 'Select a definition' 부분이 생긴다. 여기서 그룹을 선택할 수 있다.

 

@Tag

• 컨트롤러에 존재한 API를 그룹화할 태그명을 지정할 수 있다.
• 만약 태그명을 지정하지 않는다면, AuthController의 경우 auth-controller로 변환하여 API를 그룹화 한다.
• 만약 서로 다른 컨트롤러에 대해 같은 name을 적용하면 하나로 합쳐진다.

위에는 @Tag 적용, 아래는 적용 X

@RestController
@RequiredArgsConstructor
@RequestMapping("/api")
@Tag(name = "Study", description = "<b>[스터디]</b> API")
public class StudyCommandController {

 

@Operation : 각 API에 대한 설명을 추가할 수 있다.

@Operation(
        summary = "스터디 생성",
        description = "로그인한 유저가 스터디를 생성합니다."
)
public ApiResponse<Void> studyAdd(Principal principal, @Valid @RequestBody CreateStudyRequest request) {

 

@ApiResponse

• 서버에서 사용하는 응답 code과 message 값을 보여줄 수 있다.
• 커스텀 응답 코드를 사용하는 경우라면, 필수적으로 설정해주는 것이 좋다.
• 만약 @ApiResponse에 대해 설정할 것이 많다면 @ApiResponses를 먼저 추가한 다음 @ApiResponse를 넣어주면 된다.
• content 인자에 example value를 넣으면 해당 내용에 맞게 json 형식이 나타난다.

@ApiResponses({
	@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "조회 성공"),
	@io.swagger.v3.oas.annotations.responses.ApiResponse(
    		responseCode = "403",
        	description = "스터디 작성자, 참여 신청자 아님",
        	content = @Content(examples = @ExampleObject(value = SwaggerConfig.ERROR_RESPONSE))
	),
})

public static final String ERROR_RESPONSE = "{\"data\": null, \"message\": \"specific error message\"}";

 

@Schema 

• 스웨거 웹 페이지의 맨 밑에 존재하는 스키마에 대한 정보를 서술할 수 있게 해준다.
• 주로 사용하는 속성값으로는 description, defaultValue, allowableValues가 있다.
•  @Schema가 POJO(Class)의 선언부이든, 필드로 사용되는 곳이든 붙여지면 OpenAPI 문서의 components/schemas 아래에 해당 POJO(Class) 모델에 적용된다.
  • 이후 같은 클래스가 여러 곳에서 사용될 때마다 $ref: '#/components/schemas/YourClass'로 재사용하므로 모든 @Schema 설정이 적용된다.
  • 즉, 전역적으로 적용되므로 주의가 필요하다.
  • String, Long, ... 등은 OpenAPI 스펙에 이미 정의된 스칼라 타입이므로 inline(직접) 기술된다.
    
  • 즉, String 필드가 10개이고, 각 필드마다 다른 @Schema를 적용시켰을 때, 모두 다르게 나타난다.

@Schema(defaultValue = "NEWEST", allowableValues = {"NEWEST, LIKE, COMMENT"})
private SortCriteria sortCriteria = SortCriteria.NEWEST;

 

@RequestBody

• RequestBody에 대한 스웨거를 제어할 수 있는 어노테이션이다.

@io.swagger.v3.oas.annotations.parameters.RequestBody(description = "status - ACCEPTED, REJECTED만 허용")

@Parameter

• name 속성을 사용해서 쿼리 파라미터의 이름과 동일하게 맞춰줘야 한다.
  • 만약 쿼리 파라미터에 없는 name 값을 주면 새로운 쿼리 파라미터가 Swagger UI에 생긴다.
•  @ApiResponses와 마찬가지로 @Parameters를 통해 복수 개의 @Parameter를 엮어줄 수 있다.

@Parameter(
        name = "condition",
        description = """
                condition은 필수가 아니고 실질적인 요청은 쿼리 파라미터로 status=?&pageNo=?와 같습니다.</br>
                status와 pageNo 모두 필수가 아닙니다.</br>
                pageNo의 경우 기본 값으로 0이 들어가집니다.
                """
)

@ModelAttribute 예시