스웨거는 API 개발 과정에서 특히 백엔드 개발자, 프론트엔드 개발자, QA, 그리고 문서화 담당자 간의
협업을 도와주는 툴입니다.
1. 스웨거의 정의
스웨거(Swagger)는 API 설계, 문서화, 테스트 및 디버깅을 지원하는 오픈소스 프레임워크입니다.
현재는 **OpenAPI Specification(OAS)**이라는 이름으로 발전했으며, 스웨거 툴킷은 이를 기반으로 동작합니다.
2. 스웨거를 사용하는 이유
- API 문서 자동화
스웨거는 코드를 기반으로 API 명세서를 자동 생성합니다. 별도로 문서를 작성할 필요가 없어지며, 코드와 문서 간의 불일치를 방지합니다. - API 이해도 향상
API의 요청/응답 구조를 명확히 보여주기 때문에, 협업 중인 팀원들이 API를 쉽게 이해할 수 있습니다. - 개발 속도 향상
개발자는 스웨거 UI를 사용하여 직접 API를 테스트하고 확인할 수 있으므로 디버깅과 테스트 속도가 빨라집니다. - 유지보수 용이성
프로젝트 규모가 커질수록 API 문서를 갱신하기 어려워지지만, 스웨거를 사용하면 코드와 함께 문서도 자동으로 업데이트됩니다.
3. 주요 기능
- 스웨거 UI(Swagger UI)
브라우저에서 API 명세를 보기 좋게 렌더링합니다.
(위 스크린샷의 인터페이스가 바로 스웨거 UI입니다.) - 스웨거 에디터(Swagger Editor)
YAML 또는 JSON 형식으로 OpenAPI 명세를 작성하고 확인할 수 있습니다. - 스웨거 제너레이터(Swagger Codegen)
OpenAPI 명세서를 기반으로 클라이언트 및 서버 코드를 자동으로 생성합니다. - 스웨거 허브(SwaggerHub)
팀 협업을 위해 API를 설계하고 공유할 수 있는 플랫폼입니다.
스웨거를 사용해 보기위해 프로젝트 생성부터 API문서가 작성 및 확인까지 해보도록 하겠습니다
1. 프로젝트 생성
프로젝트 설정:
- Project SDK: JDK가 설치되어 있어야 합니다. 설치되어 있지 않다면, OpenJDK를 통해 설치합니다.
- Language: Java 선택
- Build system: Maven 선택
- Generators: Spring Boot 선택
아래 항목을 반드시 추가하세요:
- Spring Web: RESTful API 개발을 위해 필요
- Lombok: 코드 간소화를 위해 필요
- Spring Boot DevTools: 개발 중 편의를 위해 추가 (옵션)
- 추가적으로 Swagger를 위한 라이브러리는 나중에 pom.xml에 수동으로 추가합니다.
2. Swagger 의존성 추가하기
Swagger를 사용하려면 springdoc-openapi 라이브러리를 추가해야 합니다.
- pom.xml 파일 수정:
- dependencies 섹션에 다음을 추가합니다:
<dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId> <version>2.2.0</version> </dependency>
- 의존성 동기화:
- pom.xml 파일을 저장하고 리로드 하세요
3. 간단한 API 작성하기
컨트롤러 클래스 생성:
- src/main/java/com/example/swaggerdemo/controller 디렉토리를 만들고, HelloController.java 파일을 생성합니다.
package com.swagger.controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class HelloController {
@GetMapping("/hello")
public String hello(){
return "Hello, World!";
}
}
4. Swagger UI 확인하기
- 애플리케이션 실행:
- 인텔리제이 상단의 실행 버튼을 클릭하여 애플리케이션을 실행합니다.
- Swagger UI 접속:
- 브라우저에서 http://localhost:8080/swagger-ui/index.html에 접속합니다.
- Swagger UI가 표시되며, /hello 엔드포인트가 보일 것입니다.
- API 테스트:
- Swagger UI에서 /hello 엔드포인트를 선택한 뒤, Try it out 버튼을 클릭하여 API 호출을 테스트해볼 수 있습니다.
5. Swagger 설명 추가하기
1. @Tag
- 설명: API 그룹(카테고리)을 정의하는 어노테이션입니다.
- 사용 위치: 클래스 레벨에 사용합니다.
- 주요 속성:
- name: 태그 이름 (필수)
- description: 태그에 대한 설명 (선택)
- 결과: Swagger UI에서 User API라는 태그로 그룹화된 엔드포인트를 확인할 수 있습니다.
package com.swagger.controller;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@Tag(name = "User API", description = "사용자 관련 API입니다.")
public class HelloController {
@GetMapping("/hello")
public String hello(){
return "Hello, World!";
}
}2. @Operation
- 설명: API 엔드포인트에 대한 설명을 추가하는 어노테이션입니다.
- 사용 위치: 메서드 레벨에 사용합니다.
- 주요 속성:
- summary: API의 간단한 설명
- description: API의 상세 설명
- tags: 태그 이름을 지정하여 그룹화 (선택)
- responses: 응답 코드 및 설명을 명시 (주로 @ApiResponse와 함께 사용)
- 결과: Swagger UI에서 해당 엔드포인트의 간략 설명(summary)과 상세 설명(description)을 확인할 수 있습니다.
package com.swagger.controller;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@Tag(name = "User API", description = "사용자 관련 API입니다.")
public class HelloController {
@GetMapping("/hello")
@Operation(
summary = "사용자 조회 API",
description = "특정 ID에 해당하는 사용자의 정보를 조회합니다.",
tags = {"User API"}
)
public String hello(){
return "Hello, World!";
}
}3. @ApiResponse
- 설명: API의 응답 코드와 그에 따른 설명을 정의하는 어노테이션입니다.
- 사용 위치: @Operation 내부의 responses 속성에서 사용됩니다.
- 주요 속성:
- responseCode: HTTP 응답 코드 (예: "200", "404", "500")
- description: 응답에 대한 설명
- content: 응답 데이터의 예시(JSON 등)
- 결과: Swagger UI에서 해당 API의 각 응답 코드와 설명이 표 형식으로 나타납니다.
package com.swagger.controller;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@Tag(name = "User API", description = "사용자 관련 API입니다.")
public class HelloController {
@GetMapping("/hello")
@Operation(
summary = "사용자 조회 API",
description = "특정 ID에 해당하는 사용자의 정보를 조회합니다.",
tags = {"User API"},
responses = {
@ApiResponse(responseCode = "200", description = "성공"),
@ApiResponse(responseCode = "404", description = "실패"),
@ApiResponse(responseCode = "500", description = "서버 오류가 발생했습니다.")
}
)
public String hello(){
return "Hello, World!";
}
}4. @Parameter
- 설명: API의 요청 파라미터에 대한 정보를 추가합니다.
- 사용 위치: 메서드의 파라미터 앞에 사용합니다.
- 주요 속성:
- name: 파라미터 이름 (필수)
- description: 파라미터 설명
- required: 파라미터 필수 여부 (기본값: false)
- example: 파라미터 값의 예시
- 결과: Swagger UI에서 page와 size 파라미터가 표시되며, 각 파라미터의 설명과 예시 값을 확인할 수 있습니다.
package com.swagger.controller;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@Tag(name = "User API", description = "사용자 관련 API입니다.")
public class HelloController {
@GetMapping("/hello")
@Operation(
summary = "사용자 조회 API",
description = "특정 ID에 해당하는 사용자의 정보를 조회합니다.",
tags = {"User API"},
responses = {
@ApiResponse(responseCode = "200", description = "성공"),
@ApiResponse(responseCode = "404", description = "실패"),
@ApiResponse(responseCode = "500", description = "서버 오류가 발생했습니다.")
}
)
public String hello(
@Parameter(name = "page", description = "페이지 번호", required = true, example = "1")
int page
){
return "Hello, World!";
}
}
여기서는 User API로 했지만 실제로 유저의 정보를 가져오거나 하지는 않습니다! 어노테이션의 기능을 설명하기 위해서 이런식의 설명을 넣은거지 코드의 Getmapping은 단순 문자열 반환만 하고 있어요!
4가지 어노테이션을 모두 사용한 예시 결과
반응형
'코딩 > spring' 카테고리의 다른 글
| Spring boot에서 WebSocket + STOMP 이해 및 정리 (0) | 2025.01.14 |
|---|