➕ Swagger 띄우기

Swagger란?

• Swagger: API 문서를 자동으로 생성해주는 툴
  Swagger UI를 사용하면 웹 페이지 형태로 API를 테스트하고 확인할 수 있어서 프론트엔드와의 협업 과정에서 특히 자주 사용함.

• Spring Boot에서는 주로 Springdoc OpenAPI나 Springfox Swagger를 사용하는데, 최근에 더 많이 사용되는 Springdoc OpenAPI로 진행해보자.
  ▻ Springdoc OpenAPI는 최신 OpenAPI 3를 지원하고 Spring Boot 3.x와 호환되며 유지보수도 활발함

• 참고한 공식 문서: https://springdoc.org/

기존 프로젝트에 Swagger 적용해보기

버전 관련 메모
최신으로 갈수록 버전 호완이 안되는 경우들이 있음.. swagger 버전 2.1.0, spring 버전 3.1.4가 권장됨!

1. build.gradle 파일에 의존성 추가하기
   implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.1.0'

• 공식문서의 아래 사진의 부분을 확인해보면 groupId, artifactId, version 정보가 차례로 나와있다.
  이를 build.gradle 파일에 추가할 때에는 <groupId>:<artifactId>:<version> 형태로 추가하면 된다.
  

• 의존성 추가 후엔 반드시 🐘 새로고침 버튼 눌러주기

• 여기까지 하고 나면 http://localhost:8080/swagger-ui.html 위치에서 아래와 같이 swagger가 자동으로 생성해준 API 명세서를 확인해볼 수 있음!
  

2. Swagger 세부 설정 (선택)

• application.yml

springdoc:
  api-docs:
    path: /api-docs
  swagger-ui:
    path: /swagger-ui.html

3. API 컨트롤러에 Swagger 어노테이션 달기 (선택): Swagger에서는 어노테이션을 통해 문서에 표시될 설명을 추가할 수 있음

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;

@RestController
@RequestMapping("/api/products")
@Tag(name = "Product API", description = "상품 관련 API입니다.")
public class ProductController {

    @GetMapping
    @Operation(summary = "모든 상품 조회", description = "등록된 모든 상품을 조회합니다.")
    public List<Product> getAllProducts() {
        return productService.findAll();
    }
}

• @Tag: 이 컨트롤러가 어떤 API인지 분류
• @Operation: 각 메서드(엔드포인트)에 대한 설명