Swagger api 적용하기

✏️ Swagger

• Swagger 는 REST 웹 서비스의 설계, 빌드, 문서화, 소비하는 일을 도와주는 오픈소스 프레임워크이다.
• 간편하게 프로젝트에서 지정한 URL 들을 HTML 파일로 정리해준다.

✏️ 적용하기

📍 환경설정

• spring boot 3.x.x 부터는 spring doc 을 사용해야 한다.
  • 참고로 1.7.0 버전도 있고 dependency 도 하나로 통일됬지만 최신버전이라 그런가 공홈 자료를 보고 그대로 따라해도 작동되지 않았다.
  • 한버전을 낮춰도 지금 프로젝트 버전과 호환이 잘 되어서 최신 버전을 사용하지 않았다.
  • depenedency 추가만으로 swegger ui 사용이 가능하다.

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.1.0'

📍 Controller

🔗 Springdoc 공식문서

• depenedency 추가만으로 사용이 가능하지만 수동으로 페이지를 커스텀 할 수 있다.
  • description 엔 간단한 소개를 적으면 html 설명란에 적용된다.

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.models.Components;
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
@OpenAPIDefinition
public class BoardController {

    @Bean
    public OpenAPI api() {
        Info info = new Info().title("").version("v3").description("BAEKER-MSA : Member Server Endpoint");

        return new OpenAPI().components(new Components()).info(info);
    }
}

✏️ Swagger ui 접속

http://localhost:8080/swagger-ui/index.html

• 위 url 로 접속하면 프로젝트 내의 모든 end point 가 자동으로 정리된다.
  • Controller 별로 정리된 다음 method 별로 정리되는것 같다.
    • select 와 관련된 Controller 를 별도로 생성했는데 잘 분리한것같다.
  • 가장 밑에는 사용된 DTO 들이 정리되어있다.

• 리스트를 누르면 request 정보와 response 정보를 확인할 수 있다.
  • 투자한 리소스 대비 매우 만족스러운 기술인것같다.

✏️ 문서 작성 어노테이션

🔗 참고 블로그

📍 Endpoint 숨기기

• @Hidden
  • Class 단위, Controller 단위로 Swagger 문서에 끝점을 숨길 수 있다.

@Slf4j
@Hidden // 객체 단위로 끝점 숨기기
@RestController
@RequestMapping("/api")
@RequiredArgsConstructor
public class QuestionRestController {

📍 Endpoint 그룹 묶기

• @Tat
  • name 속성과 같은 것 끼리 api 그룹으로 묶이게된다.
  • description 속성으로 그룹의 설명을 작성할 수 있다.

@Tag // 그룹으로 묶기
@Slf4j
@RestController
@RequestMapping("/api")
@RequiredArgsConstructor
public class QuestionRestController {

📍 API 상세 정보 작성

• @Operation
  • summary 속성으로 제목을 작성 가능
  • description 속성으로 상세한 설명 작성
  • parameters 속성으로 파라미터 리스트 작성
  • responses 속성으로 응답 리스트 작성