171 lines
5.9 KiB
Markdown
171 lines
5.9 KiB
Markdown
# SpringDoc OpenAPI
|
|
|
|
`SpringDoc OpenAPI`는 Spring Boot 애플리케이션에서 **OpenAPI 3 문서를 자동으로 생성**해주는 라이브러리입니다.
|
|
기존 `SpringFox`보다 **간결하고 최신 OpenAPI 표준을 준수**하며, 유지보수가 활발한 것이 장점입니다.
|
|
|
|
**주요 특징**
|
|
* Spring Boot와 완벽한 호환
|
|
* **Swagger UI 자동 제공**
|
|
* REST API 문서를 코드에서 바로 생성
|
|
* OpenAPI 3 표준 지원
|
|
|
|
|
|
## SpringDoc OpenAPI 설정
|
|
Spring Boot 3 기준으로 **Maven 또는 Gradle**에 다음 의존성을 추가합니다.
|
|
|
|
```kotlin
|
|
implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.6")
|
|
```
|
|
|
|
Spring Boot 애플리케이션을 실행한 후, 브라우저에서 다음 URL로 접속합니다.
|
|
|
|
```
|
|
http://localhost:8080/swagger-ui.html
|
|
```
|
|
|
|
```
|
|
http://localhost:8080/v3/api-docs
|
|
```
|
|
|
|
* `swagger-ui.html`을 열면 API 문서를 자동으로 확인할 수 있습니다.
|
|
|
|
|
|
## SpringDoc OpenAPI 기본 사용법
|
|
### 컨트롤러에서 API 문서 자동 생성
|
|
아래와 같이 **Spring Boot 컨트롤러에 OpenAPI 어노테이션을 추가하면**,
|
|
Swagger 문서가 자동으로 생성됩니다.
|
|
|
|
```java
|
|
import io.swagger.v3.oas.annotations.Operation;
|
|
import io.swagger.v3.oas.annotations.tags.Tag;
|
|
import org.springframework.web.bind.annotation.*;
|
|
|
|
import java.util.List;
|
|
import java.util.Map;
|
|
|
|
@RestController
|
|
@RequestMapping("/users")
|
|
@Tag(name = "User API", description = "사용자 관리 API")
|
|
public class UserController {
|
|
|
|
@GetMapping
|
|
@Operation(summary = "사용자 목록 조회", description = "모든 사용자의 목록을 조회합니다.")
|
|
public List<Map<String, String>> getUsers() {
|
|
return List.of(Map.of("id", "1", "name", "Alice"));
|
|
}
|
|
|
|
@GetMapping("/{id}")
|
|
@Operation(summary = "사용자 정보 조회", description = "특정 사용자의 정보를 조회합니다.")
|
|
public Map<String, String> getUser(@PathVariable String id) {
|
|
return Map.of("id", id, "name", "Alice");
|
|
}
|
|
|
|
@PostMapping
|
|
@Operation(summary = "사용자 추가", description = "새로운 사용자를 추가합니다.")
|
|
public String addUser(@RequestBody Map<String, String> user) {
|
|
return "User " + user.get("name") + " added!";
|
|
}
|
|
}
|
|
```
|
|
**설명**
|
|
* `@Tag(name = "User API", description = "사용자 관리 API")` → API 그룹을 정의
|
|
* `@Operation(summary = "제목", description = "설명")` → API 설명 추가
|
|
* API 문서는 `http://localhost:8080/swagger-ui.html` 에서 확인 가능
|
|
|
|
|
|
### 요청 및 응답 모델 정의 (`@Schema`)
|
|
Swagger 문서에서 **요청과 응답 데이터를 명확하게 정의**하려면 DTO 클래스에 `@Schema` 어노테이션을 사용합니다.
|
|
|
|
```java
|
|
import io.swagger.v3.oas.annotations.media.Schema;
|
|
|
|
@Schema(description = "사용자 정보")
|
|
public class UserDto {
|
|
|
|
@Schema(description = "사용자 ID", example = "1")
|
|
private Long id;
|
|
|
|
@Schema(description = "사용자 이름", example = "Alice")
|
|
private String name;
|
|
|
|
// 생성자, Getter, Setter 생략
|
|
}
|
|
```
|
|
* `@Schema(description = "설명")` → 필드 설명 추가
|
|
* `example = "1"` → API 문서에서 예제 값 표시
|
|
|
|
|
|
### API 응답 코드 설정 (`@ApiResponse`)
|
|
각 API 메서드에 **응답 코드를 명시할 수 있습니다.**
|
|
|
|
```java
|
|
import io.swagger.v3.oas.annotations.responses.ApiResponse;
|
|
|
|
@GetMapping("/{id}")
|
|
@Operation(summary = "사용자 정보 조회", description = "특정 사용자의 정보를 조회합니다.")
|
|
@ApiResponse(responseCode = "200", description = "성공")
|
|
@ApiResponse(responseCode = "404", description = "사용자를 찾을 수 없음")
|
|
public UserDto getUser(@PathVariable Long id) {
|
|
return new UserDto(id, "Alice");
|
|
}
|
|
```
|
|
* `@ApiResponse(responseCode = "200", description = "성공")` → HTTP 응답 코드 설명 추가
|
|
|
|
|
|
## OpenAPI 문서 커스터마이징
|
|
Spring Boot의 `application.yml` 또는 `application.properties`에서 OpenAPI 문서를 설정할 수 있습니다.
|
|
|
|
```yaml
|
|
springdoc:
|
|
api-docs:
|
|
enabled: true # API 문서 활성화
|
|
swagger-ui:
|
|
path: /swagger-ui.html # Swagger UI 경로 변경
|
|
operations-sorter: method # API 정렬 방식 (메서드명 기준)
|
|
show-actuator: true # Actuator API 문서 포함 여부
|
|
```
|
|
|
|
|
|
### 커스텀 OpenAPI 설정 (Security 포함)
|
|
Spring Boot 애플리케이션에서 **JWT 인증을 Swagger UI에 적용**하려면 `OpenAPI` 빈을 직접 설정할 수도 있습니다.
|
|
|
|
```java
|
|
import io.swagger.v3.oas.models.OpenAPI;
|
|
import io.swagger.v3.oas.models.info.Info;
|
|
import io.swagger.v3.oas.models.security.SecurityRequirement;
|
|
import io.swagger.v3.oas.models.security.SecurityScheme;
|
|
import org.springframework.context.annotation.Bean;
|
|
import org.springframework.context.annotation.Configuration;
|
|
|
|
@Configuration
|
|
public class OpenApiConfig {
|
|
|
|
@Bean
|
|
public OpenAPI customOpenAPI() {
|
|
return new OpenAPI()
|
|
.info(new Info().title("사용자 API")
|
|
.version("1.0")
|
|
.description("사용자 관리 서비스"))
|
|
.addSecurityItem(new SecurityRequirement()
|
|
.addList("BearerAuth"))
|
|
.schemaRequirement("BearerAuth",
|
|
new SecurityScheme().name("Authorization")
|
|
.type(SecurityScheme.Type.HTTP)
|
|
.scheme("bearer")
|
|
.bearerFormat("JWT"));
|
|
}
|
|
}
|
|
```
|
|
* **JWT 인증을 위한 `SecurityScheme` 설정 가능**
|
|
* API 문서에 보안 설정을 추가할 수 있음
|
|
|
|
|
|
## **5. 정리**
|
|
| 기능 | 설명 |
|
|
|------|------|
|
|
| **Swagger UI** | `http://localhost:8080/swagger-ui.html`에서 확인 가능 |
|
|
| **자동 문서 생성** | `@Operation`, `@Tag` 등을 사용하여 API 설명 추가 |
|
|
| **DTO 모델 문서화** | `@Schema`를 사용하여 요청/응답 모델 정의 |
|
|
| **응답 코드 정의** | `@ApiResponse`로 HTTP 응답 코드 설명 가능 |
|
|
| **보안 적용** | JWT, OAuth2 등의 인증을 문서에 포함 가능 |
|