Merge pull request #312 from linglong67/feature/rest-docs-with-swagger

[feat] REST Docs + Swagger UI
Kernel360 · Mar 21, 2024 · 1b92d45 · 1b92d45
2 parents bb78a12 + cba85a9
commit 1b92d45
Show file tree

Hide file tree

Showing 5 changed files with 282 additions and 64 deletions.
diff --git a/module-api/build.gradle b/module-api/build.gradle
@@ -1,8 +1,15 @@
+buildscript {
+    ext {
+        restdocsApiSpecVersion = '0.17.1'
+    }
+}
+
 plugins {
     id 'java'
     id 'org.springframework.boot' version '3.2.0'
     id 'io.spring.dependency-management' version '1.1.4'
-    id "org.asciidoctor.jvm.convert" version "3.3.2"
+    id 'com.epages.restdocs-api-spec' version "${restdocsApiSpecVersion}"
+    id 'org.hidetake.swagger.generator' version '2.18.2'
 }
 
 group = 'com.kernel360'
@@ -12,10 +19,6 @@ java {
     sourceCompatibility = '17'
 }
 
-ext {
-    snippetsDir = file('build/generated-snippets')
-}
-
 configurations {
     asciidoctorExt
     compileOnly {
@@ -35,7 +38,6 @@ dependencies {
     implementation 'org.springframework.boot:spring-boot-starter-web'
     implementation 'org.springframework.boot:spring-boot-starter-aop'
     implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
-    //implementation 'org.springframework.boot:spring-boot-starter-security'
     implementation 'org.springframework.boot:spring-boot-starter-mail'
     implementation 'org.springframework.boot:spring-boot-starter-data-redis'
 
@@ -66,9 +68,10 @@ dependencies {
     testImplementation("com.navercorp.fixturemonkey:fixture-monkey-starter:1.0.0")
     testImplementation("com.navercorp.fixturemonkey:fixture-monkey-jakarta-validation:1.0.0")
 
-    // rest docs
+    // rest docs & swagger
     testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
-    asciidoctorExt 'org.springframework.restdocs:spring-restdocs-asciidoctor'
+    testImplementation 'com.epages:restdocs-api-spec-mockmvc:' + restdocsApiSpecVersion
+    swaggerUI 'org.webjars:swagger-ui:4.11.1'
 
     //actuator
     implementation 'org.springframework.boot:spring-boot-starter-actuator'
@@ -85,30 +88,42 @@ dependencies {
     annotationProcessor 'jakarta.annotation:jakarta.annotation-api'
     annotationProcessor 'jakarta.persistence:jakarta.persistence-api'
 
-    //badword Filtering
+    // badword Filtering
     implementation 'io.github.vaneproject:badwordfiltering:1.0.0'
 
-
-    // https://mvnrepository.com/artifact/org.apache.commons/commons-collections4
-    implementation group: 'org.apache.commons', name: 'commons-collections4', version: '4.4'
+    // commons-collections4
+    implementation 'org.apache.commons:commons-collections4:4.4'
 
 }
 
 tasks.named('test') {
-    outputs.dir snippetsDir
     useJUnitPlatform()
 }
 
-asciidoctor {
-    baseDirFollowsSourceFile()
-    inputs.dir snippetsDir
-    configurations 'asciidoctorExt'
-    dependsOn test
+tasks.withType(GenerateSwaggerUI) {
+    dependsOn 'openapi3'
+}
+
+swaggerSources {
+    sample {
+        setInputFile(file("${project.buildDir}/api-spec/openapi3.yaml"))
+    }
+}
+
+openapi3 {
+    servers = [
+        { url = "https://devapi.washfit.site" },
+        { url = "http://localhost:8080" }
+    ]
+    title = "API Document"
+    description = "Rest Docs With Swagger"
+    version = "0.0.1"
+    format = "yaml"
 }
 
 bootJar {
-    dependsOn asciidoctor
-    from ("${asciidoctor.outputDir}") {
+    dependsOn generateSwaggerUISample
+    from("${generateSwaggerUISample.outputDir}") {
         into 'static/docs'
     }
 }

diff --git a/module-api/src/main/java/com/kernel360/global/filter/LogFilter.java b/module-api/src/main/java/com/kernel360/global/filter/LogFilter.java
@@ -61,7 +61,7 @@ private static void printLog(FilterChain chain, ContentCachingRequestWrapper req
         });
 
         String responseBody = new String(response.getContentAsByteArray());
-        if(!deninedList().containsKey(uri)) {
+        if(!deninedList().containsKey(uri) && !uri.startsWith("/docs/")) {
             log.info("##### RESPONSE ##### uri: {}, method: {}, header: {}, body: {}", uri, method, responseHeaderValues, responseBody);
         }
         response.copyBodyToResponse();

diff --git a/module-api/src/test/java/com/kernel360/common/ControllerTest.java b/module-api/src/test/java/com/kernel360/common/ControllerTest.java
@@ -6,6 +6,7 @@
 import com.kernel360.commoncode.controller.CommonCodeController;
 import com.kernel360.commoncode.service.CommonCodeService;
 import com.kernel360.global.Interceptor.AcceptInterceptor;
+import com.kernel360.global.Interceptor.InterceptorConfig;
 import com.kernel360.main.controller.MainController;
 import com.kernel360.main.service.MainService;
 import com.kernel360.member.controller.MemberController;
@@ -14,6 +15,8 @@
 import com.kernel360.mypage.controller.MyPageController;
 import com.kernel360.product.controller.ProductController;
 import com.kernel360.product.service.ProductService;
+import com.kernel360.review.controller.ReviewController;
+import com.kernel360.review.service.ReviewService;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
 import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
@@ -26,7 +29,8 @@
         ProductController.class,
         MainController.class,
         MyPageController.class,
-        AuthController.class
+        AuthController.class,
+        ReviewController.class
 })
 @AutoConfigureRestDocs
 public abstract class ControllerTest {
@@ -37,6 +41,9 @@ public abstract class ControllerTest {
     @Autowired
     protected ObjectMapper objectMapper;
 
+    @MockBean
+    protected InterceptorConfig interceptorConfig;
+
     @MockBean
     protected AcceptInterceptor acceptInterceptor;
 
@@ -57,4 +64,7 @@ public abstract class ControllerTest {
 
     @MockBean
     protected AuthService authService;
+
+    @MockBean
+    protected ReviewService reviewService;
 }
diff --git a/...i/src/test/java/com/kernel360/commoncode/controller/CommonCodeControllerRestDocsTest.java b/...i/src/test/java/com/kernel360/commoncode/controller/CommonCodeControllerRestDocsTest.java
@@ -1,26 +1,27 @@
 package com.kernel360.commoncode.controller;
 
+import com.epages.restdocs.apispec.ResourceSnippetParameters;
+import com.epages.restdocs.apispec.Schema;
+import com.kernel360.common.ControllerTest;
+import com.kernel360.commoncode.dto.CommonCodeDto;
+import org.junit.jupiter.api.Test;
+import org.springframework.restdocs.payload.JsonFieldType;
+import org.springframework.test.web.servlet.ResultActions;
+
+import java.time.LocalDateTime;
+import java.util.Arrays;
+import java.util.List;
+
+import static com.epages.restdocs.apispec.MockMvcRestDocumentationWrapper.document;
+import static com.epages.restdocs.apispec.ResourceDocumentation.resource;
 import static com.kernel360.common.utils.RestDocumentUtils.getDocumentRequest;
 import static com.kernel360.common.utils.RestDocumentUtils.getDocumentResponse;
 import static org.mockito.BDDMockito.given;
-import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
 import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get;
-import static org.springframework.restdocs.payload.PayloadDocumentation.beneathPath;
 import static org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath;
-import static org.springframework.restdocs.payload.PayloadDocumentation.responseFields;
 import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName;
-import static org.springframework.restdocs.request.RequestDocumentation.pathParameters;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
 
-import com.kernel360.common.ControllerTest;
-import com.kernel360.commoncode.dto.CommonCodeDto;
-import java.time.LocalDateTime;
-import java.util.Arrays;
-import java.util.List;
-import org.junit.jupiter.api.Test;
-import org.springframework.restdocs.payload.JsonFieldType;
-import org.springframework.test.web.servlet.ResultActions;
-
 // FIXME :: 삭제 예정 파일입니다
 class CommonCodeControllerRestDocsTest extends ControllerTest {
 
@@ -64,39 +65,38 @@ void commmonCodeSearch() throws Exception {
 
 
         //then
-        //pathParameters, pathParameters, requestFields, responseFields는 필요 시 각각 작성
         result.andExpect(status().isOk())
               .andDo(document(
                       "commoncode/get-common-codes",
                       getDocumentRequest(),
                       getDocumentResponse(),
-                      pathParameters(
-                              parameterWithName("codeName").description("코드명")
-                      ),
-//                      queryParameters(
-//                              parameterWithName("size").description("size").optional(),
-//                              parameterWithName("page").description("page").optional()
-//                      ),
-//                      requestFields(
-//                              fieldWithPath("codeName").type(JsonFieldType.STRING).description("코드명"),
-//                              fieldWithPath("upperName").type(JsonFieldType.STRING).description("상위 코드명").optional()
-//                      ),
-//                      responseFields(
-//                              fieldWithPath("codeNo").type(JsonFieldType.NUMBER).description("코드번호"),
-//                      )
-                      responseFields(beneathPath("value").withSubsectionId("value"),
-                              fieldWithPath("codeNo").type(JsonFieldType.NUMBER).description("코드번호"),
-                              fieldWithPath("codeName").type(JsonFieldType.STRING).description("코드명"),
-                              fieldWithPath("upperNo").type(JsonFieldType.NUMBER).description("상위 코드번호").optional(),
-                              fieldWithPath("upperName").type(JsonFieldType.STRING).description("상위 코드명").optional(),
-                              fieldWithPath("sortOrder").type(JsonFieldType.NUMBER).description("정렬순서"),
-                              fieldWithPath("isUsed").type(JsonFieldType.BOOLEAN).description("사용여부"),
-                              fieldWithPath("description").type(JsonFieldType.STRING).description("설명"),
-                              fieldWithPath("createdAt").type(JsonFieldType.STRING).description("생성일시"),
-                              fieldWithPath("createdBy").type(JsonFieldType.STRING).description("생성자"),
-                              fieldWithPath("modifiedAt").type(JsonFieldType.STRING).description("수정일시").optional(),
-                              fieldWithPath("modifiedBy").type(JsonFieldType.STRING).description("수정자").optional()
-                      )
-              ));
+                      resource(ResourceSnippetParameters
+                              .builder()
+                              .tag("CommonCode API")
+                              .summary("공통코드 조회")
+                              .pathParameters(
+                                      parameterWithName("codeName").description("코드명")
+                              )
+                              .responseFields(
+                                      fieldWithPath("status").type(JsonFieldType.NUMBER).description("상태"),
+                                      fieldWithPath("code").type(JsonFieldType.STRING).description("응답 코드"),
+                                      fieldWithPath("message").type(JsonFieldType.STRING).description("응답 메시지"),
+                                      fieldWithPath("value").type(JsonFieldType.ARRAY).description("응답 데이터 리스트"),
+                                      fieldWithPath("value[].codeNo").type(JsonFieldType.NUMBER).description("코드번호"),
+                                      fieldWithPath("value[].codeName").type(JsonFieldType.STRING).description("코드명"),
+                                      fieldWithPath("value[].upperNo").type(JsonFieldType.NUMBER).description("상위 코드번호").optional(),
+                                      fieldWithPath("value[].upperName").type(JsonFieldType.STRING).description("상위 코드명").optional(),
+                                      fieldWithPath("value[].sortOrder").type(JsonFieldType.NUMBER).description("정렬순서"),
+                                      fieldWithPath("value[].isUsed").type(JsonFieldType.BOOLEAN).description("사용여부"),
+                                      fieldWithPath("value[].description").type(JsonFieldType.STRING).description("설명"),
+                                      fieldWithPath("value[].createdAt").type(JsonFieldType.STRING).description("생성일시"),
+                                      fieldWithPath("value[].createdBy").type(JsonFieldType.STRING).description("생성자"),
+                                      fieldWithPath("value[].modifiedAt").type(JsonFieldType.STRING).description("수정일시").optional(),
+                                      fieldWithPath("value[].modifiedBy").type(JsonFieldType.STRING).description("수정자").optional()
+                              )
+                              .requestSchema(Schema.schema("공통코드 조회"))
+                              .responseSchema(Schema.schema("공통코드 조회"))
+                              .build()
+                      )));
     }
 }