🔧 chore: 스웨거 세팅

🔧 chore: 스웨거 세팅

Author: frombunny

build.gradle

@@ -24,16 +24,26 @@ repositories {
 }
 
 dependencies {
+	// JPA
 	implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
 
 	implementation 'org.springframework.boot:spring-boot-starter-web'
+
+	// Lombok
 	compileOnly 'org.projectlombok:lombok'
+
 	runtimeOnly 'com.mysql:mysql-connector-j'
 	annotationProcessor 'org.projectlombok:lombok'
 	testImplementation 'org.springframework.boot:spring-boot-starter-test'
 	testImplementation 'org.springframework.security:spring-security-test'
 	testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
 
+	// Swagger UI
+	implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.7.0'
+
+	implementation 'org.apache.commons:commons-lang3:3.12.0'
+
+	// Validation
 	implementation 'org.springframework.boot:spring-boot-starter-validation'
 
 }

src/main/java/com/example/Centralthon/domain/order/web/controller/OrderApi.java

@@ -0,0 +1,74 @@
+package com.example.Centralthon.domain.order.web.controller;
+
+import com.example.Centralthon.domain.order.web.dto.CompleteOrderReq;
+import com.example.Centralthon.domain.order.web.dto.CreateOrderReq;
+import com.example.Centralthon.domain.order.web.dto.CreateOrderRes;
+import com.example.Centralthon.global.response.SuccessResponse;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.ExampleObject;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import org.springframework.http.ResponseEntity;
+
+@Tag(name = "Orders", description = "주문/픽업 관련 API")
+public interface OrderApi {
+
+    @Operation(
+            summary = "주문 생성",
+            description = "픽업 예약을 생성합니다. 완료 시 픽업 코드와 주문한 가게들의 기본키를 반환합니다."
+    )
+    @ApiResponse(
+            responseCode = "201",
+            description = "주문 생성 성공",
+            content = @Content(
+                    mediaType = "application/json",
+                    schema = @Schema(implementation = SuccessResponse.class),
+                    examples = @ExampleObject(
+                            name = "SUCCESS_201",
+                            value = """
+                    {
+                      "timestamp": "2025-08-15 04:22:54",
+                      "code": "SUCCESS_201",
+                      "httpStatus": 201,
+                      "message": "호출에 성공하였습니다.",
+                      "data": {
+                        "code": "PE8512",
+                        "storeList": [1, 3]
+                      },
+                      "isSuccess": true
+                    }
+                    """
+                    )
+            )
+    )
+    ResponseEntity<SuccessResponse<CreateOrderRes>> createOrder(CreateOrderReq orderReq);
+
+    @Operation(
+            summary = "픽업 완료 처리",
+            description = "픽업 코드를 사용하여 주문을 픽업 완료로 처리합니다."
+    )
+    @ApiResponse(
+            responseCode = "200",
+            description = "픽업 완료 성공",
+            content = @Content(
+                    mediaType = "application/json",
+                    schema = @Schema(implementation = SuccessResponse.class),
+                    examples = @ExampleObject(
+                            name = "SUCCESS_200",
+                            value = """
+                    {
+                      "timestamp": "2025-08-15 04:45:14",
+                      "code": "SUCCESS_200",
+                      "httpStatus": 200,
+                      "message": "호출에 성공하였습니다.",
+                      "data": null,
+                      "isSuccess": true
+                    }
+                    """
+                    )
+            )
+    )
+    ResponseEntity<SuccessResponse<?>> completePickUp(CompleteOrderReq completeOrderReq);
+}

src/main/java/com/example/Centralthon/domain/order/web/controller/OrderController.java

@@ -15,16 +15,18 @@
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/api/orders")
-public class OrderController {
+public class OrderController implements OrderApi {
     private final OrderService orderService;
 
     @PostMapping
+    @Override
     public ResponseEntity<SuccessResponse<CreateOrderRes>> createOrder(@RequestBody @Valid CreateOrderReq orderReq) {
         CreateOrderRes createOrderRes = orderService.orderMenus(orderReq);
         return ResponseEntity.status(HttpStatus.CREATED).body(SuccessResponse.of(createOrderRes, SuccessResponseCode.SUCCESS_CREATED));
     }
 
     @PutMapping("/complete")
+    @Override
     public ResponseEntity<SuccessResponse<?>> completePickUp(@RequestBody @Valid CompleteOrderReq completeOrderReq){
         orderService.completePickUp(completeOrderReq);
         return ResponseEntity.status(HttpStatus.OK).body(SuccessResponse.empty());

src/main/java/com/example/Centralthon/global/config/SwaggerConfig.java

@@ -0,0 +1,22 @@
+package com.example.Centralthon.global.config;
+
+import io.swagger.v3.oas.models.Components;
+import io.swagger.v3.oas.models.OpenAPI;
+import io.swagger.v3.oas.models.info.Info;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+@Configuration
+public class SwaggerConfig {
+    @Bean
+    public OpenAPI openAPI(){
+        Info info = new Info()
+                .title("잔반플러팅 API Document")
+                .version("v0.0.1")
+                .description("잔반 플러팅 API 명세서입니다.");
+
+        return new OpenAPI()
+                .components(new Components())
+                .info(info);
+    }
+}

src/main/resources/application.properties

@@ -12,4 +12,12 @@ spring.datasource.password=${DATABASE_PASSWORD}
 spring.jpa.hibernate.ddl-auto=update
 spring.jpa.show-sql=true
 spring.jpa.properties.hibernate.format_sql=true
-spring.jpa.properties.hibernate.use_sql_comments=true
+spring.jpa.properties.hibernate.use_sql_comments=true
+
+# Swagger
+springdoc.swagger-ui.path=/swagger-ui.html
+springdoc.api-docs.path=/api-docs
+springdoc.group-configs[0].group=default
+springdoc.group-configs[0].paths-to-match=/**
+springdoc.api-docs.enabled=true
+springdoc.swagger-ui.enabled=true