[API] Spring boot + Swagger 3 (SpringDOC, OpenAPI) 적용 및 사용법

 

 

https://swagger.io/

API Documentation & Design Tools for Teams | Swagger

 

 

 

https://devel-log.tistory.com/43 

[API] Spring boot Swagger 기본 사용법

 

 

이전에 Swagger2 관련하여 사용법을 포스팅한 적이 있다.

Swagger3를 사용하게 되어 3 관련 포스팅을 새로 한다.

 

개발환경은 이전과 동일하다.

 

Spring Boot

Maven

Java 8

Swagger 2.9.2

 

 

Swagger 의존성 추가 - pom.xml

 

<!-- swagger -->
<dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>2.9.2</version>
</dependency>

<dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger-ui</artifactId>
      <version>2.9.2</version>
</dependency>

 

 

 

Application.yml 설정

 

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

 

 

 

Swagger 설정 추가 - SwaggerConfig

 

나는 Swagger2로 사용하던 페이지와 비슷한 형태로 만들려고 한다.

그러려면 그룹화를 해야 한다.

 

API 그룹화

 

그룹에 따라 API를 필터링해서 조회 할 수 있다.

patchsToMatch()로 url로 필터할 수 있고, packagesToScan() 으로 package단위로 설정할 수도 있다.

 

    // 그룹별 Api 메뉴 설정
    // 그룹화를 정의할 개수에 따라 GroupedOpenApi 빈을 등록해준다.
    @Bean
    public GroupedOpenApi allApi() {
        return GroupedOpenApi.builder()
                .group("전체")
                .pathsToMatch("/**") // url로 필터
                .packagesToScan("kr.co.test") // package 단위로 필터
                .build();
    }

 

 

그룹화를 설정하지 않고 실행 시 해당 화면처럼 보인다.

 

 

 

 

SwaggerConfig - OpenAPI

 

 

@Configuration // 설정 파일 읽어오기
public class SwaggerConfig {
	
    // 그룹별 Api 메뉴 설정
    // 그룹화를 정의할 개수에 따라 GroupedOpenApi 빈을 등록해준다.
    @Bean
    public GroupedOpenApi allApi() {
        return GroupedOpenApi.builder()
                .group("전체")
                .pathsToMatch("/**") // url로 필터
                .packagesToScan("kr.co.test") // package 단위로 필터
                .build();
    }
    
    @Bean
    public GroupedOpenApi groupApi2() {
        return GroupedOpenApi.builder()
                .group("그룹명2")
                .pathsToMatch("/url 경로")
                .build();
    }
    
    @Bean
    public GroupedOpenApi groupApi3() {
        return GroupedOpenApi.builder()
                .group("그룹명3")
                .pathsToMatch("/url 경로")
                .build();
    }
    
    // Api 설정
    @Bean
    public OpenAPI openAPI(@Value("${springdoc.version}") String appVersion) {
        Info info = new Info()
                .title("제목")
                .version(appVersion)
                .description("설명")
                .contact(new Contact().name("test").url("http://www.test.co.kr").email("test.test.com"));

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

 

 

서버 실행 후 아래 형태의 주소로 접속한다.

Swagger2와의 차이점은 뒤에 /index.html 이 붙는다.

 

Swagger2 URL

 

localhost:[port]/swagger-ui.html

 

Swagger3 URL

 

localhost:[port]/swagger-ui/index.html

 

 

 

SwaggerConfig 적용 후 우측 상단에 카테고리가 생긴다.

기존 Swagger2 처럼 원하는 메뉴만 볼 수 있다.

 

 

 

 

Controller 및 Entity 설정은 Swagger2 와 비슷한데 Annotations 이 좀 달라졌다.

이번에 사용하는 SpringDOC는 Swagger3 annotations 을 사용하고 있다.

 

 

Swagger 3 annotations	Swagger 2 annotations	desc
@Tag	@Api	클래스를 Swagger 리소스로 표시
@Schema	@ApiModel @ApiModelProperty	Swagger 모델에 대한 추가 정보를 제공
@Schema(accessMode = READ_ONLY)	@ApiModelProperty(hidden = true)	모델 속성 추가 및 변경
@Parameter(hidden = true) or @Operation(hidden = true) or @Hidden	@ApiIgnore	API 작업에서 단일 매개 변수를 나타냄
@Parameter	@ApiParam  @ApiImplicitParam	작업 매개 변수에 대한 추가 메타 데이터를 추가 API 작업에서 단일 매개 변수를 나타냄
@Parameters	@ApiImplicitParams	API 작업에서 복수 매개 변수를 나타냄
@Operation(summary = "foo", description = "bar")	@ApiOperation(value = "foo", notes = "bar")	특정 경로에 대한 작업 또는 일반적으로 HTTP 메서드를 설명
@ApiResponse(responseCode = "404", description = "foo")	@ApiResponse(code = 404, message = "foo")	작업의 가능한 응답을 설명

 

 

 

 

Swagger Controller 적용

* Swagger 검색 시 모든 블로그에 예시 이미지가 있어 별도 캡처하지 않음.

 

@RestController
@Tag(name = "Test API", description = "Test API 입니다.") // 대제목 지정
public class SwaggerController {

    /**Pretreatment 페이징 목록 조회 */
    @Operation(summary = "목록 조회", description = "<strong>목록을 조회합니다.</strong>")  // 각 API(메소드)명칭/설명 추가
    @ApiResponses({@ApiResponse(responseCode = "200", description = "조회 성공")})
    public ResponseEntity<Object> getTestMethod() {
     	. . .
    }

 

 

@Tag - 각 패키지별 대제목 지정

 

@Operation - 각 API(Method) 명칭/설명 추가

 

@ApiResponse - 해당 Method의 Response 내용 변경

• Config 에서 ResponseMessage 처리 하는 것과 동일하다.
• 각 Method별 에러코드 별도 지정이 가능하다. (코드가 길어짐)

/** 목록 조회*/
@ApiResponses({
    @ApiResponse(code=200, message="성공입니다."),
    @ApiResponse(code=400, message="비정상적인 접근입니다.")
})
public ResponseEntity<Object> getTestMethod() {
    생략;
}

 

 

 

* 동일 Response Message를 Controller method 전체에 적용하고 싶다면

method가 아닌 Controller단에 @ApiResponses를 적용해주면 된다.

 

@ApiResponses({@ApiResponse(code=200, message="성공 하였습니다.")})
public class SwaggerController {
	...
}

 

 

 

@ Parameter - 해당 API Method 호출에 필요한 Parameter 명칭/설명 추가

 

@ApiImplicitParam(name = "svcId", value="서비스 ID" ,required = true)
public ResponseEntity<Object> getTestMethod(@PathVariable(name="svcId") String svcId) {
    . . .
}

 

public void downloadFile(@Parameter(description = "서비스 ID", required = true) @PathVariable String svcId,
    		@Parameter(description = "정보 ID", required = true) @PathVariable String infoId){
            
}

 

 

Controller 단에서는 기존에 method 상단에 @ApiImplicitParam 을 사용해서 적용해줬었는데,

Swagger3는 @Parameter() 를 통해서 적용해주면 된다.

 

 

@Schema - DTO(VO) Field 명칭 지정 / 예제 및 설명 추가

 

• 해당 DTO(VO) Field의 예제 Data를 추가 할 수 있다.
• 응답 받는 데이터 값을 쉽게 알 수 있다.
• name은 생략 가능하다.

// Swagger2
@ApiParam(value="서비스 명")
@ApiModelProperty(notes="서비스 명", example="")
private String svcNm;

// Swagger3
@Schema(description = "서비스 명", defaultValue = "")
private String svcNm;

 

 

 

 

 

기존에 Swagger2 를 사용한 사람이라면 Swagger3가 확실히 조금 더 발전했다는걸 느낄 수 있을 것 같다.

Config 설정이 좀 더 간편해져서 좋다.