2025-04-08T19:56:24

docs/41_openapi-doc.md

@@ -0,0 +1,170 @@
+# 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 등의 인증을 문서에 포함 가능 |