[Backend] Swagger 설정

1. Swagger

• 개발한 Rest API를 편리하게 문서화하는 것
• 이를 통해서 관리 및 제 3의 사용자가 편리하게 API를 호출해보고 테스트 할 수 있는 도구

2. SpringBoot에서 Swagger 설정

• build.gradle 파일에 dependency 추가

// Swagger
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'

• main에 config 파일 추가

package com.example.paymentsystem.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI().info(new Info().title("결제 시스템 API").description("결제 시스템 API 명세").version("0.1"));
    }
}

• controller나 dto에 특정 annotation 붙여서 swagger 설정 추가 가능
  • controller
    • class 위에 @Tag를 통해 API 그룹 설정 가능
      • name: 태그의 이름
      • description: 태그에 대한 설명
      • ex) @Tag(name = "LoginController", description = "로그인 API")
    • method 위에 @Operation를 통해 API 상세 정보 설정 가능
      • summary: API에 대한 간략한 설명
      • description: API에 대한 상세 설명
      • response: API Response 리스트
      • parameters: API 파라미터 리스트
      • ex) @Operation(summary = "로그인 API", description = "이메일과 비밀번호를 통해 로그인 성공 여부를 확인합니다.")
  • dto
    • 각 변수에 @Schema를 통해 API Schema 설정 가능
      • description : 한글명
      • defaultValue : 기본값
      • ex) @Schema(description = "이메일")
• http://localhost:8080/swagger-ui/index.html 를 통해서 접속 가능

3. Swagger와 Spring Rest Docs 차이

	Swagger	Spring Rest Docs
장점	문서 상에서 API를 바로 테스트할 수 있다.	소스 코드에 영향을 주지 않는다.
	테스트 코드가 필요 없어서 적용하기 쉽다.	테스트 코드가 성공해야 문서를 작성할 수 있다.
단점	소스 코드에 테스트와 관련된 annotation을 추가한다.	테스트 코드를 작성해야 해서 적용이 어렵다.
	소스 코드에 추가되기 때문에 코드가 지저분할 수 있다.	문서를 위한 테스트 코드를 관리해야 한다.

• 간편한 API 동작을 확인하고 싶을 때는 Swagger을 사용하는 것이 적합하다.
• 테스트 성공 기반으로 문서를 작성해야 하면 Spring Rest Docs를 사용하는 것이 적합하다.