> 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/developer-guide-en/dev-start/search-and-other-environment-settings/swagger3.md). # Swagger3 {% hint style="info" %} **Reference** Swagger3 Site ( Swagger3 Sample Site: {% endhint %} This page covers Swagger3. Explains the annotation changes in the Swagger3 version and how to write them in Java source code. *** ## Description Starting with Spring Boot 3.0, the existing swagger2 spec (springfox-swagger2) is no longer supported, and the swagger3 spec, springdoc-openapi, is used instead. X2BEE uses the springdoc-openapi-starter-webmvc-ui 3.0.0 dependency and runs on Spring Boot 4.x. **None of the annotations previously used with swagger2 can be used anymore; you must use the newly changed swagger3 annotations.** ## Annotation Changes (Important) Below is the annotation mapping from Swagger2 -> Swagger3 (for reference). ``` @ApiParam -> @Parameter @ApiOperation -> @Operation @Api -> @Tag @ApiImplicitParams -> @Parameters @ApiImplicitParam -> @Parameter @ApiIgnore -> @Parameter(hidden = true) or @operation(hidden = true) or @hidden @apimodel -> @Schema @ApiModelProperty -> @Schema ``` ## Controller-Related Annotations (Summary) * @Tag * Description: An annotation for configuring API groups. Use the name attribute to set the tag's name, and the description attribute to add a description of the tag. Entries with the same name set in @Tag are grouped together into one API group. * Example attributes: name, description * Example:

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

* @Operation * Description: An annotation for configuring the API group. Use the name attribute to set the tag's name, and the description attribute to add a description of the tag. Entries with the same name set in @Tag are grouped together into one API group. * Example:

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

* @ApiResponses / @ApiResponse * Description: Groups or singly uses @ApiResponse to configure the response. Use responseCode to set the HTTP status code, and description to add an explanation. The response body structure can be specified via content's schema or implementation. * Key attributes: responseCode, description, content (schema, hidden, implementation) * Example (multiple):

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

* Example (single):

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

* @Parameters / @Parameter * Description: Groups or singly uses @Parameter to define API parameters. You can set name, description, in (query|header|path|cookie), required, schema, and more. * Example (multiple):

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

* Example (single):

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

## Request / Response Objects (@Schema) * @Schema * Description: An annotation for configuring request/response objects (DTOs). You can set description, defaultValue, example, allowableValues, and more. * Key attributes: description, defaultValue, allowableValues, example, nullable, maxLength, etc. * Example:

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

* DTOs assigned with @Schema are added to and can be viewed in the Schemas section of the Swagger UI. ## Swagger Configuration Example * OpenAPI Bean configuration example:

@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 Examples * Example using @Tag:

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

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

Another example:

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

## Example Request/Response DTO Files * **@Schema Placement** ``` @Schema(description = "(샘플) 우편번호 조회 요청 DTO") public class SampleZipNoMgmtRequest { .... } ``` ``` @Schema(description = "(샘플) 우편번호 조회 응답 DTO") public class SampleZipNoMgmtResponse{ .... } ``` When the @Schema annotation is applied, it is added and can be checked in the Schemas section at the bottom of the page. * **@Schema - description, example** ``` @Schema(description = "시도명", example = "서울특별시") private String ctpNmParam; ```

Clicking ctpNmParam shows the following (String example description)\ \ ![](https://200425-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVEZx3rsZsIv89GPS3d2J%2Fuploads%2FNjKL7YuEVI3ANEzkCb5C%2Fimage.png?alt=media\&token=193bdb84-1c34-42f3-ae32-48c346bd1d39) When writing the @Schema example, set it as the req parameter. * **@Schema - defaultValue, allowableValues** ``` @Schema(description = "검색어 코드", defaultValue = "2", allowableValues = {"1", "2"}) private String paramCd; ``` defaultValue\ The @Schema defaultValue can be configured, and like example, it is set as the req parameter. allowableValues\ When writing @Schema allowableValues, you can see the allowed values as an enumeration.