Swagger3

참고

Swagger3 Site (https://springdoc.org/) Swagger3 Sample Site: https://beta-venus-api-sample.x2bee.com/api/sample/swagger-ui/index.html#/

다음은 Swagger3에 대해 다룹니다.

Swagger3 버전에서의 어노테이션 변경점과 자바 소스 내에서 작성 방법에 대해 설명합니다.

---

설명

스프링 부트 3.0부터는 기존 swagger2 스펙(springfox-swagger2)을 지원하지 않고, swagger3 스펙인 springdoc-openapi를 사용합니다. X2BEE는 springdoc-openapi-starter-webmvc-ui 3.0.0 의존성을 사용하며 Spring Boot 4.x 에서 동작합니다.

기존에 swagger2 사용하던 어노테이션은 모두 사용할 수 없으며, 새롭게 변경된 swagger3의 어노테이션을 사용해야 합니다.

어노테이션 변경 (중요)

다음은 Swagger2 -> Swagger3(설명용) 어노테이션 매핑입니다.

@ApiParam           -> @Parameter  
@ApiOperation       -> @Operation
@Api                -> @Tag
@ApiImplicitParams  -> @Parameters
@ApiImplicitParam   -> @Parameter
@ApiIgnore          -> @Parameter(hidden = true) or @operation(hidden = true) or @hidden
@apimodel           -> @Schema
@ApiModelProperty   -> @Schema

컨트롤러 관련 어노테이션 (요약)

• @Tag

  • 설명: API 그룹 설정을 위한 어노테이션입니다. name 속성으로 태그의 이름을 설정할 수 있고, description 속성으로 태그에 대한 설명을 추가할 수 있습니다. @Tag에 설정된 name이 같은 것 끼리 하나의 API 그룹으로 묶입니다.

  • 속성 예: name, description

  • 예제:

    UserController.java

    @Tag(name = "user", description = "사용자 API")
    public class UserController {
        ...
    }

• @Operation

  • 설명: api 그룹 설정을 위한 어노테이션입니다.name 속성으로 태그의 이름을 설정할 수 있고, description 속성으로 태그에 대한 설명을 추가할 수 있습니다.

    @Tag에 설정된 name이 같은 것 끼리 하나의 api 그룹으로 묶게 됩니다.

  • 예제:

    UserController.java

    @Operation(summary = "사용자 등록", description = "사용자를 신규 등록합니다.")
    public Long save(@RequestBody UserRequestDto dto) {
        return userService.save(dto);
    }

• @ApiResponses / @ApiResponse

  • 설명: @ApiResponse를 그룹화하거나 단건으로 사용하여 response 설정을 합니다. responseCode로 HTTP 상태 코드를 설정하고 description으로 설명을 추가합니다. content의 schema 또는 implementation으로 응답 바디 구조를 지정할 수 있습니다.

  • 주요 속성: responseCode, description, content (schema, hidden, implementation)

  • 예제(여러개):

    PostsController.java

    @ApiResponses(value = {
      @ApiResponse(responseCode = "200", description = "게시글 조회 성공",
        content = @Content(schema = @Schema(implementation = PostsResponseDto.class))),
      @ApiResponse(responseCode = "404", description = "존재하지 않는 리소스 접근",
        content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
    })
    public PostsResponseDto findById(@PathVariable Long id) {
      return postsService.findById(id);
    }

  • 예제(단건):

    SampleController.java

    @ApiResponse(responseCode = "200", description = "(샘플) 조회 성공",
      content = @Content(schema = @Schema(implementation = SampleZipNoMgmtResponse.class)))
    public PostsResponseDto findById(...) { ... }

• @Parameters / @Parameter

  • 설명: @Parameter를 그룹화하거나 단건으로 사용해 API 파라미터를 정의합니다. name, description, in(query|header|path|cookie), required, schema 등을 설정할 수 있습니다.

  • 예제(여러개):

    ExampleController.java

    @Parameters({
      @Parameter(name = "siteNo", description = "사이트번호", required = true, in = ParameterIn.PATH, schema = @Schema(type = "Integer")),
      @Parameter(name = "mallNo", description = "몰번호", required = true, in = ParameterIn.PATH, schema = @Schema(type = "String")),
      @Parameter(name = "dshopTypCd", description = "전시매장유형코드", required = true, in = ParameterIn.PATH, schema = @Schema(type = "String")),
      @Parameter(name = "dshopNo", description = "전시매장번호", required = false, in = ParameterIn.PATH, schema = @Schema(type = "String"))
    })
    public PostsResponseDto findById(...) { ... }

  • 예제(단건):

    ExampleController.java

    @Parameter(name = "id", description = "posts 의 id", in = ParameterIn.PATH)
    @PathVariable Long id
    public PostsResponseDto findById(...) { ... }

Request / Response 객체 관련 (@Schema)

• @Schema

  • 설명: Request, Response 객체(DTO)에 대한 설정을 위한 어노테이션입니다. description, defaultValue, example, allowableValues 등을 설정할 수 있습니다.

  • 주요 속성: description, defaultValue, allowableValues, example, nullable, maxLength 등.

  • 예제:

    UserResponseDto.java

    @Schema(description = "사용자 응답DTO")
    @Getter
    public class UserResponseDto {
      @Schema(description = "사용자 ID")
      private Long id;
    
      @Schema(description = "이메일", nullable = false, example = "[e-mail]")
      private String email;
    
      @Schema(description = "이름")
      private String name;
    
      @Pattern(regexp = "[1-2]")
      @Schema(description = "성별", defaultValue = "1", allowableValues = {"1", "2"})
      private String sex;
    
      @DateTimeFormat(pattern = "yyMMdd")
      @Schema(description = "생년월일", example = "yyMMdd", maxLength = 6)
      private String birthDate;
    
      @Schema(description = "전화번호")
      private String phoneNumber;
    
      @Schema(description = "수정일자")
      private LocalDateTime modifiedDate;
    }

  • @Schema로 할당된 DTO들은 Swagger UI의 Schemas 섹션에 추가되어 확인할 수 있습니다.

Swagger 설정 예시

• OpenAPI Bean 설정 예제:

  SwaggerConfig.java

  @Bean
  public OpenAPI openAPI() {
    Info info = new Info().title("X2BEE Sample API")
      .description("X2BEE Sample REST API 설명서입니다.")
      .version("v1")
      .contact(new Contact().name("플래티어").url("https://www.plateer.com/company/plateer").email(""));
  
    return new OpenAPI().info(info);
  }

Swagger3 Controller 예시

• @Tag 사용 예:

  Swagger3Controller.java

  @Tag(name = "swagger", description = "Swagger Swagger3Controller API")
  public class Swagger3Controller {
    ...
  }

• @Operation, @ApiResponses 사용 예:

  Swagger3Controller.java

  @Operation(summary = "(샘플) 주소 리스트 조회", description = "(샘플) 주소지 정보를 조회합니다.", tags = {"swagger"})
  @ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "(샘플) 조회 성공",
      content = @Content(schema = @Schema(implementation = SampleZipNoMgmtResponse.class)))
  })
  @GetMapping("/getZipNoList")
  public List<SampleZipNoMgmtResponse> getZipNoList(SampleZipNoMgmtRequest req) {
    ...
  }

  또 다른 예:

  Swagger3Controller.java

  @ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "(샘플) 조회 성공",
      content = @Content(schema = @Schema(implementation = SampleZipNoMgmtResponse.class))),
    @ApiResponse(responseCode = "404", description = "(샘플) 존재하지 않는 리소스 접근",
      content = @Content(schema = @Schema(implementation = String.class)))
  })

Request/Response DTO 예시 파일들

• @ Schema 위치

@Schema(description = "(샘플) 우편번호 조회 요청 DTO")
public class SampleZipNoMgmtRequest {
    ....
}

@Schema(description = "(샘플) 우편번호 조회 응답 DTO")
public class SampleZipNoMgmtResponse{
    ....
}

@schema 어노테이션 할당시, 페이지 하단의 Schemas에 추가되어 확인 가능합니다.

• @Schema-description, example

@Schema(description = "시도명", example = "서울특별시")
private String ctpNmParam;

ctpNmParam 클릭시, 다음과 같이 확인 ( String example description )

@Schema example 작성시, req parameter 로 설정합니다.

• @Schema - defaultValue, allowableValues

@Schema(description = "검색어 코드", defaultValue = "2", allowableValues = {"1", "2"})
private String paramCd;

defaultValue @Schema defaultValue 설정가능하며 example과 마찬가지로 req parameter 로 설정합니다.

allowableValues @Schema allowableValues 작성시 허용값을 열거형으로 확인 가능합니다.