API를 다 만들었다면 프론트엔드 개발자가 호출할 수 있도록 "설명서"를 제공해야 합니다. 수동으로 엑셀이나 위키에 작성하면 코드가 수정될 때마다 업데이트하기 매우 고통스럽습니다. Swagger(springdoc) 라이브러리를 하나만 추가하면, 현재 코드를 분석해 예쁜 웹 페이지 형태의 API 문서를 자동 생성해 줍니다.
build.gradle에 implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0' 단 한 줄만 추가하고 서버를 켜면 /swagger-ui.html 경로에서 멋진 문서를 볼 수 있습니다. (Spring Boot 3.x 기준)
| 어노테이션 | 설명 (Swagger UI에 표시되는 내용) |
|---|---|
@Tag(name="...", description="...") |
컨트롤러 클래스 레벨에 붙여서 API 그룹의 이름과 설명을 정의합니다. |
@Operation(summary="...") |
각 API 메서드가 어떤 역할을 하는지 한 줄 요약을 적어줍니다. |
@Parameter(description="...") |
요청 파라미터(예: id, name)의 상세한 의미를 설명합니다. |