Spring Boot, Swagger란?

API는 애플리케이션 간에 데이터를 주고 받거나 서비스를 요청하고 제공하기 위한 인터페이스 이다.

클라이어느와 서버 간에 API를 통해 통신하는 만큼 API 문서화는 개발 과정에 있어 중요한 요소 중 하나이다.

Spring Framework에서 API 문서화 방법에는 크게 Rest Docs와 Swagger 2가지가 존재한다.

---

Spring REST Docs

스프링 프레임워크에서 제공하는 API 문서 자동화 도구이다.

테스트 기반으로 문서화가 동작하기에 문서의 정확성을 보장하는데 도움이 된다.

 

Swagger

API를 문서화하고 테스트할 수 있는 오픈 소스 프레임워크이다.

테스트를 기반으로 문서화를 진행하는 Spring REST Docs와 달리 어노테이션을 통해 간편하게 API 문서를 자동으로 만들 수 있다.

자체적으로 사용자 친화적인 UI도 제공해주고 있어 문서를 쉽게 읽고 테스트할 수 있다.

---

Swagger 설정 라이브러리

- SpringFox (2020.7 이후 업데이트 Stop)

- SpringDoc (지속적으로 지원 중)

 

springdoc-openapi 라이브러리

- OpenAPI 3

- Spring Boot V3

- JSR-303

- Swagger-ui

- OAuth2

---

어노테이션

API 문서화에 적용할 수 있는 많은 어노테이션이 존재

 

@Tag

API 엔드포인트에 태그를 할당하여 관련된 엔드포인트를 그룹화하고 문서에서 카테고리를 형성하는데 사용.

(주로 @RestController가 붙어있는 클래스에 사용)

@Tag(name="테스트", description="테스트 API")

name : 카테고리 이름

description : 설명

 

 

 

@Operation

Swagger에서 API 문서를 자동으로 생성할 때 사용.

API 엔드포인트의 작업에 대한 설명을 추가하고 세부 정보를 제공하는데 사용된다.

(주로 @RestController 클래스 내부의 메서드에 사용된다.)

@Operation(summary="테스트 조회", description="서버의 작동 여부 확인을 위해 테스트 조회")

summary 속성 : API의 간단한 설명을 제공

security 속성 : API에 대한 인증 및 보안 요구사항을 명시

 

@SecurityRequirement 를 사용하여 Swagger UI에 인증 요구사항을 표시 할 수 있다.

@Operation(summary="테스트 조회", description="서버의 작동 여부 확인을 위해 테스트 조회"
			, security = @SecurityRequirement(name = AuthConstant.SWAGGER_HEADER_AUTH)))

 

 

 

@ApiResponse

API 응답에 대한 설명과 상태 코드를 정의하는데 사용

@Operation(summary="테스트 조회", description="서버의 작동 여부 확인을 위해 테스트 조회")
@ApiResponses({
	@ApiResponse(responseCode="200", description="조회 성공"),
    @ApiResponse(responseCode="400", description="조회 실패")
})

여러개의 @ApiResponse 등록 가능

 

 

 

@Schema

API 모델의 속성을 정의하고 문서화하는데 사용

즉, 요청과 응답에 사용되는 DTO 클래스나 필드에 사용할 수 있다.

@Schema(description="테스트 응답")
public class TestCheckDto{
	@Schema(description="테스트 코드", example="1000")
    private int code;
    
    @Schema(description="테스트 메시지", example="Test 응답")
}

description : 속성 설명

example : 예시 값을 정의