Swagger 3.0 - 2

📝 Swagger 3.0

저번에 Swagger의 초기설정에 대해서 정리해보았는데, 이번에는 실제로 사용하는 Anntation에 관해서 정리해보려고 한다.

---

🚩 @Tag

※ Source Example

@Tag(name = "Template", description = "Template Description")
public interface ITemplateController {
}

■ name

• Tag의 이름을 표시한다.
• Tag에 설정된 Name이 같은 것끼리 하나의 API 그룹으로 묶는다.

■ desciption

• Tag에 대한 설명을 표시한다.

Example Image

🚩 @Operation

※ Source Example

public interface ITemplateController {
    @Operation(summary = "Get Request Template", description = "HttpMethod.Get Method 를 이용한 HTTP Request / 단순 데이터 조회에 주로 사용")
    ResponseEntity<ResponsePayload> httpMethodGet(@ModelAttribute GetMethodRequestPayload payload);

■ summary

• API에 관한 간략한 설명을 표시한다.

■ desciption

• API의 상세한 설명을 표시한다.

Example Image

🚩 @ParameterObject

• RequestBody를 사용하지 않는다고 선언해주는 Anntation이다. 따라서 Swagger Web Page에 해당 Operation에서 RequestBody 부분이 생략된다.

※ Source Example

public interface ITemplateController {
    @Operation(summary = "Get Request Template", description = "HttpMethod.Get Method 를 이용한 HTTP Request / 단순 데이터 조회에 주로 사용")
    ResponseEntity<ResponsePayload> httpMethodGet(@ParameterObject @ModelAttribute GetMethodRequestPayload payload);

Example Image

🚩 @Parameters

• Parameter Annotation을 사용하기 위한 선언적 Annotation이다.
  
  

※ Source Example

public interface ITemplateController {
    @Operation(summary = "Get Request Template", description = "HttpMethod.Get Method 를 이용한 HTTP Request / 단순 데이터 조회에 주로 사용")
    @Parameters({
            @Parameter(name = "userId", description = "데이터 조회에 사용되는 String Parameter"),
            @Parameter(name = "name", description = "데이터 조회에 사용되는 String Parameter"),
            @Parameter(name = "age", description = "데이터 조회에 사용되는 Integer Parameter")
    })
    ResponseEntity<ResponsePayload> httpMethodGet(@ModelAttribute GetMethodRequestPayload payload);

🚩 @Parameter

※ Source Example

public interface ITemplateController {
    @Operation(summary = "Get Request Template", description = "HttpMethod.Get Method 를 이용한 HTTP Request / 단순 데이터 조회에 주로 사용")
    @Parameters({
            @Parameter(name = "userId", description = "데이터 조회에 사용되는 String Parameter"),
            @Parameter(name = "name", description = "데이터 조회에 사용되는 String Parameter"),
            @Parameter(name = "age", description = "데이터 조회에 사용되는 Integer Parameter")
    })
    ResponseEntity<ResponsePayload> httpMethodGet(@ModelAttribute GetMethodRequestPayload payload);

■ name

• Parameter 이름을 표시한다.

■ description

• Parameter의 설명을 표시한다.

■ in ( ParameterIn.Default, .query, .header, .path, .cookie )

• Parameter의 기본적인 위치를 설정한다.

Example Image

🚩 @ApiResponses

• ApiResponse Annotation을 사용하기 위한 선언적 Annotation이다.

※ Source Example

@Operation(summary = "Get Request Template", description = "HttpMethod.Get Method 를 이용한 HTTP Request / 단순 데이터 조회에 주로 사용")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "success", content = @Content(schema = @Schema(implementation = GetMethodResponsePayload.class))),
            @ApiResponse(responseCode = "400", description = "bad request", content = @Content(schema = @Schema(implementation = ResponsePayload.class)))
    })
    ResponseEntity<ResponsePayload> httpMethodGet(@ParameterObject @ModelAttribute @Validated GetMethodRequestPayload payload, BindingResult error) throws CustomRunTimeException;

🚩 @ApiResponse

※ Source Example

@Operation(summary = "Get Request Template", description = "HttpMethod.Get Method 를 이용한 HTTP Request / 단순 데이터 조회에 주로 사용")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "success", content = @Content(schema = @Schema(implementation = GetMethodResponsePayload.class))),
            @ApiResponse(responseCode = "400", description = "bad request", content = @Content(schema = @Schema(implementation = ResponsePayload.class)))
    })
    ResponseEntity<ResponsePayload> httpMethodGet(@ParameterObject @ModelAttribute @Validated GetMethodRequestPayload payload, BindingResult error) throws CustomRunTimeException;

■ responseCode

• 반환해줄 ReseponseCode를 표시한다.

■ description

• 반환해줄 객체에 대한 설명이 표시된다.

■ content

• 반환해줄 객체에 대한 타입이 정의된다.

Example Image

🚩 @Content

※ Source Example

@Operation(summary = "Get Request Template", description = "HttpMethod.Get Method 를 이용한 HTTP Request / 단순 데이터 조회에 주로 사용")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "success", content = @Content(schema = @Schema(implementation = GetMethodResponsePayload.class))),
            @ApiResponse(responseCode = "400", description = "bad request", content = @Content(schema = @Schema(implementation = ResponsePayload.class)))
    })
    ResponseEntity<ResponsePayload> httpMethodGet(@ParameterObject @ModelAttribute @Validated GetMethodRequestPayload payload, BindingResult error) throws CustomRunTimeException;

■ hidden ( true, false )

• Schema 숨김 여부를 설정한다.

■ implementation

• Schema 대상 클래스를 설정한다.
• 하단의 직접적인 @Schema Anntation과는 같은 Annotation이다.

🚩 @Schema

※ Source Example

public class PostMethodRequestPayload extends RequestPayload {
    @NotBlank
    @Schema(description = "데이터 조회에 사용되는 String Parameter / NotBlank", defaultValue = "userId")
    private String userId;

    @NotEmpty
    @Schema(description = "데이터 조회에 사용되는 String Parameter / NotEmpty", defaultValue = "userName")
    private String name;

    @NotNull
    @Schema(description = "데이터 조회에 사용되는 Integer Parameter / NotNull", defaultValue = "20")
    private int age;
}

■ desciption

• Schema에 대한 설명이 표시된다.

■ defaultValue

• 기본적으로 설정되는 값이 표시된다.

■ allowableValues

• 가능한 값들을 표시해주는 기능이다.

Example Image

---

📌 마무리

기본적으로 내가 실무에서 사용하던 Swagger Anntation에 관해서 정리해보았다.
이정도만 알고있어서 개발자들간의 API 문서로 분쟁이 생길만한 일은 없는거 같다.
나중에 시간이 된다면 더 세세한 기능을 정리하여 업로드 하려고 한다.