swagger 기반 API 문서 작성

.gitignore

@@ -38,3 +38,6 @@ out/
 
 ### .env ###
 .env
+
+# Generated Swagger UI
+src/main/resources/static/docs/

build.gradle

@@ -3,6 +3,8 @@ plugins {
     id 'jacoco'
     id 'org.springframework.boot' version '3.5.9'
     id 'io.spring.dependency-management' version '1.1.7'
+    id 'com.epages.restdocs-api-spec' version '0.19.4'
+    id 'org.hidetake.swagger.generator' version '2.19.2'
 }
 
 group = 'com.recyclestudy'
@@ -35,9 +37,17 @@ dependencies {
     annotationProcessor 'org.projectlombok:lombok'
 
     testImplementation 'org.springframework.boot:spring-boot-starter-test'
-    testRuntimeOnly 'com.h2database:h2'
     testImplementation 'io.rest-assured:rest-assured'
+    testRuntimeOnly 'com.h2database:h2'
     testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
+
+    // api docs
+    testImplementation 'org.springframework.restdocs:spring-restdocs-restassured'
+    testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
+    testImplementation 'com.epages:restdocs-api-spec-restassured:0.19.4'
+    implementation 'com.epages:restdocs-api-spec-mockmvc:0.19.4'
+
+    swaggerUI 'org.webjars:swagger-ui:5.30.3'
 }
 
 tasks.named('test') {
@@ -73,3 +83,33 @@ jacocoTestReport {
     dependsOn test
 }
 
+openapi3 {
+    servers = [
+            { url = "http://localhost:8080" }
+    ]
+    title = "Recycle-Study Server API Document"
+    description = "응답 테스트 검증이 완료된 명세서입니다."
+    version = "0.0.1"
+    format = "yaml"
+}
+
+swaggerSources {
+    sample {
+        setInputFile(file("${project.buildDir}/api-spec/openapi3.yaml"))
+    }
+}
+
+tasks.withType(GenerateSwaggerUI).configureEach {
+    dependsOn 'openapi3'
+}
+
+tasks.register('copySwaggerDocument', Copy) {
+    dependsOn generateSwaggerUI
+
+    from file("build/swagger-ui-sample/")
+    into file("src/main/resources/static/docs")
+}
+
+bootJar {
+    dependsOn copySwaggerDocument
+}

src/main/java/com/recyclestudy/exception/GlobalControllerAdvice.java

@@ -3,6 +3,7 @@
 import com.recyclestudy.exception.dto.ErrorResponse;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.MissingServletRequestParameterException;
 import org.springframework.web.bind.annotation.ExceptionHandler;
 import org.springframework.web.bind.annotation.RestControllerAdvice;
 
@@ -39,6 +40,13 @@ public ResponseEntity<ErrorResponse> handleIllegalArgument(final IllegalArgument
         return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(response);
     }
 
+    @ExceptionHandler(MissingServletRequestParameterException.class)
+    public ResponseEntity<ErrorResponse> handleMissingServletRequestParameter(
+            final MissingServletRequestParameterException e) {
+        final ErrorResponse response = ErrorResponse.from(e.getMessage());
+        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(response);
+    }
+
     @ExceptionHandler(Exception.class)
     public ResponseEntity<ErrorResponse> handleException(final Exception e) {
         final ErrorResponse response = ErrorResponse.from("예기치 못한 에러가 발생했습니다");