[Spring] Spring 3버전에 Springdoc 라이브러리를 사용해 swagger 적용하기

Springfox가 아닌 Springdoc으로 Swgger를 사용하는 이유 

이전 Spring 에서 swagger를 사용할 때 springfox를 사용했는데 

springdoc 에서 제공하는 swagger를 더 선호한다고해서 사용해보았다. 

springdoc는 webflux도 지원하며 더 사용하기 쉽다고 한다. 

 

 

Springdoc 사용하기 

spring boot버전에 따라서 springdoc코드를 추가한다. 

spring boot 3버전부터 springdoc 2버전을 사용해야지 오류가 안난다. 

 

 

build.gradle

//swagger
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'

 

 

 

config 파일 

Springdoc에서는 config 클래스에서 기본 설명만 작성하고 나머지 설정은 application.yaml/application.properties에서 설정한다. 

 

Springdoc의 GroupedOpenApi를 통해 API를 분류하여 API spec을 문서화할 수 있다.

• group : Swagger문서에서의 definition 이름
• pathsToMatch : url을 통해 Swagger문서의 그룹을 나눈다

package com.example.test.config;

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import java.util.Arrays;

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI openAPI(@Value("${springdoc.version}") String appVersion) {
        return new OpenAPI()
                .info(new Info().title("Swagger 제목")
                        .description("Swagger 설명 API")
                        .version("v1.0.0"))
                .components(new Components().addSecuritySchemes("authorization",new SecurityScheme()
                        .type(io.swagger.v3.oas.models.security.SecurityScheme.Type.APIKEY)
                        .description("jwt api key")
                        .in(io.swagger.v3.oas.models.security.SecurityScheme.In.HEADER).name("Authorization")))
                .security(Arrays.asList(new SecurityRequirement().addList("authorization")));
    }

    @Bean
    public GroupedOpenApi apiInfo() {
        return GroupedOpenApi.builder()
                .group("사용자 API")
                .pathsToMatch("/api/v1/**")
                .build();
    }
    
    @Bean
    public GroupedOpenApi getMemberApi() {
        return GroupedOpenApi.builder()
                .group("회원 API")
                .pathsToMatch("/api/v1/member/**")
                .build();

    }

}

 

• info : OpenApi의 기본 설정
• version : Swagger 문서 버전 표기
• description : Swagger 문서 설명
• title : Swagger 문서 제목

 

 

controller

import com.example.test.config.enums.ErrorCodeEnum;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;


@Slf4j
@RestController
@RequiredArgsConstructor
@RequestMapping(value = "/api/v1/members")
@Tag(name = "00. 사용자", description = "사용자 정보 API")
public class MemberController {

    @Operation(summary = "사용자 정보 목록 조회", description = "사용자 정보 목록 조회")
    @GetMapping("/list")
    public String findMember2() {
        log.info("list ok");
        log.info(ErrorCodeEnum.SYSTEM_ERROR.name());

        return "list ok";
    }
    
}

 

 

태그 내용은 공식 문서를 참고해서 사용한다.

https://springdoc.org/#migrating-from-springfox

• @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")

 

 

 

 

application.yaml

springdoc:
  api-docs:
    path: /api/v1/api-docs
    enabled: true
  swagger-ui:
    operations-sorter: method
    path: /swagger-ui/index.html
    disable-swagger-default-url: true
    display-request-duration: true
    query-config-enabled: true
    doc-expansion: none
    url: /api/v1/api-docs

 

• api-docs.enable: true
  • swagger 사용 여부 설정(default = true)
• operations-sorter
  • 태그 내 API의 정렬 기준
  • alpha : 알파벳 오름차순
  • method : http method 순서
•  path
  • swagger 접속 path 설정
• doc-expansion
  • tag와 operation을 펼치는 방식 (list, full, none)
  • default = none (모두 닫힌 상태)

 

 

 

페이지 접근 경로 

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