Merge pull request #113 from onetime-with-members/feature/#112/restdocs

[feat] : REST Docs & Swagger 설정을 추가한다

.github/workflows/dev-cicd.yml

@@ -36,7 +36,7 @@ jobs:
         run: chmod +x ./gradlew
 
       - name: ⏱️gradle build 중입니다.
-        run: ./gradlew build -x test
+        run: ./gradlew clean build openapi3 asciidoctor
 
       - name: ⏱️Docker Hub에 로그인합니다.
         uses: docker/login-action@v2

.github/workflows/test-cicd.yml

@@ -36,7 +36,7 @@ jobs:
         run: chmod +x ./gradlew
 
       - name: ⏱️gradle build 중입니다.
-        run: ./gradlew build -x test
+        run: ./gradlew clean build openapi3 asciidoctor
 
       - name: ⏱️Docker Hub에 로그인합니다.
         uses: docker/login-action@v2

build.gradle

@@ -2,6 +2,11 @@ plugins {
     id 'java'
     id 'org.springframework.boot' version '3.3.2'
     id 'io.spring.dependency-management' version '1.1.6'
+
+    // REST Docs
+    id "org.asciidoctor.jvm.convert" version "3.3.2"
+    id 'com.epages.restdocs-api-spec' version '0.19.2'
+    id 'org.hidetake.swagger.generator' version '2.18.2'
 }
 
 group = 'side'
@@ -50,10 +55,75 @@ dependencies {
     implementation 'io.jsonwebtoken:jjwt-api:0.12.2'
     implementation 'io.jsonwebtoken:jjwt-impl:0.12.2'
     implementation 'io.jsonwebtoken:jjwt-jackson:0.12.2'
+    // REST Docs & Swagger
+    testImplementation 'com.epages:restdocs-api-spec-mockmvc:0.19.2'
+    testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc:3.0.0'
+    testImplementation 'com.squareup.okhttp3:mockwebserver'
+    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.1.0'
+}
+
+// QueryDSL 디렉토리
+def querydslDir = "src/main/generated"
+
+// REST Docs & Swagger 설정
+ext {
+    snippetsDir = file('build/generated-snippets')
 }
 
 tasks.named('test') {
     useJUnitPlatform()
+    outputs.dir snippetsDir
+}
+
+sourceSets {
+    test {
+        java {
+            srcDirs = ['src/test/java']
+        }
+    }
+}
+
+def serverUrl = "https://onetime-test.store"
+
+openapi3 {
+    server = serverUrl
+    title = "OneTime API Documentation"
+    description = "Spring REST Docs with Swagger UI."
+    version = "0.0.1"
+    outputFileNamePrefix = 'open-api-3.0.1'
+    format = 'json'
+    outputDirectory = 'build/resources/main/static/docs'
+}
+
+tasks.withType(GenerateSwaggerUI).configureEach {
+    dependsOn 'openapi3'
+
+    delete file('src/main/resources/static/docs/')
+    copy {
+        from "build/resources/main/static/docs"
+        into "src/main/resources/static/docs/"
+    }
+}
+
+tasks.named('asciidoctor') {
+    inputs.dir snippetsDir
+    dependsOn test
+}
+
+tasks.named("bootJar") {
+    dependsOn asciidoctor
+    from("${asciidoctor.outputDir}") {
+        into 'static/docs'
+    }
+    dependsOn ':openapi3'
+}
+
+tasks.register('copyDocument', Copy) {
+    dependsOn asciidoctor
+    from file(project.layout.buildDirectory.dir("docs/asciidoc").get().asFile.path)
+    into file("src/main/resources/static/docs")
 }
 
-def querydslDir = "src/main/generated"
+tasks.named("build") {
+    dependsOn copyDocument
+}

src/main/java/side/onetime/global/common/status/ErrorStatus.java

@@ -17,6 +17,7 @@ public enum ErrorStatus implements BaseErrorCode {
     _METHOD_NOT_ALLOWED(HttpStatus.METHOD_NOT_ALLOWED, "405", "허용되지 않은 요청 메소드입니다."),
     _UNSUPPORTED_MEDIA_TYPE(HttpStatus.UNSUPPORTED_MEDIA_TYPE, "415", "지원되지 않는 미디어 타입입니다."),
     _NOT_FOUND_HANDLER(HttpStatus.NOT_FOUND, "404", "해당 경로에 대한 핸들러를 찾을 수 없습니다."),
+    _FAILED_TRANSLATE_SWAGGER(HttpStatus.INTERNAL_SERVER_ERROR, "500", "Rest Docs로 생성된 json파일을 통한 스웨거 변환에 실패하였습니다.")
     ;
 
     private final HttpStatus httpStatus;

src/main/java/side/onetime/global/config/SwaggerConfig.java

@@ -0,0 +1,51 @@
+package side.onetime.global.config;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+import io.swagger.v3.oas.models.OpenAPI;
+import io.swagger.v3.oas.models.Paths;
+import io.swagger.v3.oas.models.info.Info;
+import io.swagger.v3.oas.models.servers.Server;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.core.io.ClassPathResource;
+import side.onetime.exception.CustomException;
+import side.onetime.global.common.status.ErrorStatus;
+
+import java.io.InputStream;
+import java.util.List;
+
+@Configuration
+public class SwaggerConfig {
+
+    @Bean
+    public OpenAPI customOpenAPI() {
+        OpenAPI openAPI = new OpenAPI()
+                .info(new Info().title("OneTime API Documentation").version("0.0.1").description("Spring REST Docs with Swagger UI."))
+                .servers(List.of(
+                        new Server().url("http://localhost:8090").description("로컬 서버"),
+                        new Server().url("https://onetime-test.store").description("테스트 서버")
+                ));
+
+        // REST Docs에서 생성한 open-api-3.0.1.json 파일 읽어오기
+        try {
+            ClassPathResource resource = new ClassPathResource("static/docs/open-api-3.0.1.json");
+            InputStream inputStream = resource.getInputStream();
+            ObjectMapper mapper = new ObjectMapper();
+
+            // open-api-3.0.1.json 파일을 OpenAPI 객체로 매핑
+            OpenAPI restDocsOpenAPI = mapper.readValue(inputStream, OpenAPI.class);
+
+            // REST Docs에서 생성한 Paths 정보 병합
+            Paths paths = restDocsOpenAPI.getPaths();
+            openAPI.setPaths(paths);
+
+            openAPI.components(restDocsOpenAPI.getComponents());
+
+        } catch (Exception e) {
+            throw new CustomException(ErrorStatus._FAILED_TRANSLATE_SWAGGER);
+        }
+
+        return openAPI;
+    }
+}

src/main/resources/static/docs/open-api-3.0.1.json

@@ -0,0 +1,16 @@
+{
+  "openapi" : "3.0.1",
+  "info" : {
+    "title" : "OneTime API Documentation",
+    "description" : "Spring REST Docs with Swagger UI.",
+    "version" : "0.0.1"
+  },
+  "servers" : [ {
+    "url" : "https://onetime-test.store"
+  } ],
+  "tags" : [ ],
+  "paths" : { },
+  "components" : {
+    "schemas" : { }
+  }
+}