> For the complete documentation index, see [llms.txt](https://tech.x2bee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tech.x2bee.com/dev-guide/dev-start/undefined-1/swagger3.md). # Swagger3 {% hint style="info" %} **참고** Swagger3 Site ( Swagger3 Sample Site: {% endhint %} 다음은 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 * 예제:

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

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

@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) * 예제(여러개):

@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);
    }

* 예제(단건):

@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 등을 설정할 수 있습니다. * 예제(여러개):

@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(...) { ... }

* 예제(단건):

@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 등. * 예제:

@Schema(description = "사용자 응답DTO")
    @Getter
    public class UserResponseDto {
      @Schema(description = "사용자 ID")
      private Long id;

      @Schema(description = "이메일", nullable = false, example = "abc@jiniworld.me")
      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 설정 예제:

@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 사용 예:

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

* @Operation, @ApiResponses 사용 예:

@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) {
    ...
  }

또 다른 예:

@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 )\ \ ![](/files/A5JYayzgy0glcUcIgXzF) @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 작성시 허용값을 열거형으로 확인 가능합니다.