Merge pull request #3 from YAPP-Github/test/documentation

[Test] Rest Docs + Swagger UI를 이용한 문서화 환경 세팅

Author: leegwichan

.gitignore

@@ -35,3 +35,6 @@ out/
 
 ### VS Code ###
 .vscode/
+
+### Rest Docs Documentation ###
+/src/main/resources/static/docs/openapi3.yaml

build.gradle

@@ -3,6 +3,10 @@ plugins {
     id 'org.springframework.boot' version '3.5.0'
     id 'io.spring.dependency-management' version '1.1.7'
     id 'org.asciidoctor.jvm.convert' version '3.3.2'
+
+    // Rest Docs & Swagger UI
+    id 'com.epages.restdocs-api-spec' version '0.18.2'
+    id 'org.hidetake.swagger.generator' version '2.18.2'
 }
 
 group = 'baegam'
@@ -46,14 +50,45 @@ dependencies {
     testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
     testImplementation 'org.springframework.boot:spring-boot-starter-test'
     testImplementation 'io.rest-assured:rest-assured:5.5.0'
+
+    // Documentation
+    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0'
+    testImplementation 'org.springframework.restdocs:spring-restdocs-restassured'
+    testImplementation 'com.epages:restdocs-api-spec-mockmvc:0.18.2'
+    testImplementation 'com.epages:restdocs-api-spec-restassured:0.18.2'
+}
+
+bootJar {
+    dependsOn("openapi3")
 }
 
 tasks.named('test', Test) {
     outputs.dir snippetsDir
     useJUnitPlatform()
 }
 
-tasks.named('asciidoctor') {
-    inputs.dir snippetsDir
-    dependsOn test
+generateSwaggerUI {
+    dependsOn("openapi3")
+
+    delete(fileTree("src/main/resources/static/docs/") {
+        exclude(".gitkeep")
+    })
+    copy {
+        from("build/resources/main/static/docs/")
+        into("src/main/resources/static/docs/")
+    }
+}
+
+openapi3 {
+    servers = [ // 서버 상황에 맞춰 추가 예정
+            {
+                url = "http://localhost:8080"
+                description = "Local Server"
+            }
+    ]
+    title = "백암 순대 API" // 수정 예정
+    description = "백암 순대 API" // 수정 예정
+    version = "0.0.1"
+    format = "yaml"
+    outputDirectory = "build/resources/main/static/docs"
 }

src/main/resources/application.yml

@@ -0,0 +1,9 @@
+springdoc:
+  swagger-ui:
+    path: /docs/swagger
+    url: /docs/openapi3.yaml
+    disable-swagger-default-url: true
+    filter: true
+    persist-authorization: true
+    display-request-duration: true
+    default-model-expand-depth: 10

src/main/resources/static/docs/.gitkeep

@@ -0,0 +1,55 @@
+package baegam.sundae.document;
+
+import io.restassured.RestAssured;
+import io.restassured.builder.RequestSpecBuilder;
+import io.restassured.specification.RequestSpecification;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.boot.test.web.server.LocalServerPort;
+import org.springframework.restdocs.RestDocumentationContextProvider;
+import org.springframework.restdocs.RestDocumentationExtension;
+import org.springframework.restdocs.restassured.RestAssuredRestDocumentation;
+import org.springframework.restdocs.restassured.RestAssuredRestDocumentationConfigurer;
+import org.springframework.restdocs.restassured.RestDocumentationFilter;
+
+@ExtendWith({RestDocumentationExtension.class, MockitoExtension.class})
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
+public abstract class BaseDocumentTest {
+
+    // @MockitoBean 을 이용하여 Service Layer 및 특정 객체 Mocking
+
+    @LocalServerPort
+    private int port;
+
+    private RequestSpecification spec;
+
+
+    @BeforeEach
+    void setEnvironment(RestDocumentationContextProvider restDocumentation) {
+        RestAssured.port = port;
+        RestAssuredRestDocumentationConfigurer webConfigurer =
+                RestAssuredRestDocumentation.documentationConfiguration(restDocumentation);
+        spec = new RequestSpecBuilder()
+                .addFilter(webConfigurer)
+                .build();
+    }
+
+    protected final RestDocsRequest request() {
+        return new RestDocsRequest();
+    }
+
+    protected final RestDocsResponse response() {
+        return new RestDocsResponse();
+    }
+
+    protected final RestDocsFilterBuilder document(String identifierPrefix, int statusCode) {
+        return new RestDocsFilterBuilder(identifierPrefix, Integer.toString(statusCode));
+    }
+
+    protected RequestSpecification given(RestDocumentationFilter documentationFilter) {
+        return RestAssured.given(spec)
+                .filter(documentationFilter);
+    }
+}

src/test/java/baegam/sundae/document/BaseDocumentTest.java

@@ -0,0 +1,67 @@
+package baegam.sundae.document;
+
+import static com.epages.restdocs.apispec.RestAssuredRestDocumentationWrapper.document;
+
+import com.epages.restdocs.apispec.ResourceSnippetParametersBuilder;
+import java.util.ArrayList;
+import java.util.List;
+import org.springframework.http.HttpHeaders;
+import org.springframework.restdocs.operation.preprocess.OperationRequestPreprocessor;
+import org.springframework.restdocs.operation.preprocess.OperationResponsePreprocessor;
+import org.springframework.restdocs.operation.preprocess.Preprocessors;
+import org.springframework.restdocs.restassured.RestDocumentationFilter;
+import org.springframework.restdocs.snippet.Snippet;
+
+public class RestDocsFilterBuilder {
+
+    private static final String IDENTIFIER_DELIMITER = "/";
+    private static final OperationRequestPreprocessor REQUEST_PREPROCESSOR = Preprocessors.preprocessRequest(
+            Preprocessors.prettyPrint(),
+            Preprocessors.modifyHeaders()
+                    .remove(HttpHeaders.HOST)
+                    .remove(HttpHeaders.CONTENT_LENGTH)
+    );
+    private static final OperationResponsePreprocessor RESPONSE_PREPROCESSOR = Preprocessors.preprocessResponse(
+            Preprocessors.prettyPrint(),
+            Preprocessors.modifyHeaders()
+                    .remove(HttpHeaders.TRANSFER_ENCODING)
+                    .remove(HttpHeaders.DATE)
+                    .remove(HttpHeaders.CONNECTION)
+                    .remove(HttpHeaders.CONTENT_LENGTH)
+    );
+
+    private final String identifier;
+    private final List<Snippet> snippets;
+    private ResourceSnippetParametersBuilder resourceBuilder;
+
+    private RestDocsFilterBuilder(String identifier) {
+        this.identifier = identifier;
+        this.resourceBuilder = new ResourceSnippetParametersBuilder();
+        this.snippets = new ArrayList<>();
+    }
+
+    public RestDocsFilterBuilder(String identifierPrefix, String identifier) {
+        this(identifierPrefix + IDENTIFIER_DELIMITER + identifier);
+    }
+
+    public RestDocsFilterBuilder request(RestDocsRequest request) {
+        resourceBuilder = request.getResourceBuilder();
+        snippets.addAll(request.getSnippets());
+        return this;
+    }
+
+    public RestDocsFilterBuilder response(RestDocsResponse response) {
+        snippets.addAll(response.getSnippets());
+        return this;
+    }
+
+    public RestDocumentationFilter build() {
+        return document(
+                identifier,
+                resourceBuilder,
+                REQUEST_PREPROCESSOR,
+                RESPONSE_PREPROCESSOR,
+                snippets.toArray(Snippet[]::new)
+        );
+    }
+}

src/test/java/baegam/sundae/document/RestDocsFilterBuilder.java

@@ -0,0 +1,75 @@
+package baegam.sundae.document;
+
+import static org.springframework.restdocs.cookies.CookieDocumentation.requestCookies;
+import static org.springframework.restdocs.headers.HeaderDocumentation.requestHeaders;
+import static org.springframework.restdocs.payload.PayloadDocumentation.requestFields;
+import static org.springframework.restdocs.request.RequestDocumentation.pathParameters;
+import static org.springframework.restdocs.request.RequestDocumentation.queryParameters;
+
+import com.epages.restdocs.apispec.ResourceSnippetParametersBuilder;
+import java.util.LinkedList;
+import java.util.List;
+import org.springframework.restdocs.cookies.CookieDescriptor;
+import org.springframework.restdocs.headers.HeaderDescriptor;
+import org.springframework.restdocs.payload.FieldDescriptor;
+import org.springframework.restdocs.request.ParameterDescriptor;
+import org.springframework.restdocs.snippet.Snippet;
+
+public class RestDocsRequest {
+
+    private final ResourceSnippetParametersBuilder resourceBuilder;
+    private final List<Snippet> snippets;
+
+    public RestDocsRequest() {
+        this.resourceBuilder = new ResourceSnippetParametersBuilder();
+        this.snippets = new LinkedList<>();
+    }
+
+    public RestDocsRequest tag(Tag tag) {
+        resourceBuilder.tag(tag.getDisplayName());
+        return this;
+    }
+
+    public RestDocsRequest summary(String summary) {
+        resourceBuilder.summary(summary);
+        return this;
+    }
+
+    public RestDocsRequest description(String description) {
+        resourceBuilder.description(description);
+        return this;
+    }
+
+    public RestDocsRequest pathParameter(ParameterDescriptor... descriptors) {
+        snippets.add(pathParameters(descriptors));
+        return this;
+    }
+
+    public RestDocsRequest queryParameter(ParameterDescriptor... descriptors) {
+        snippets.add(queryParameters(descriptors));
+        return this;
+    }
+
+    public RestDocsRequest requestHeader(HeaderDescriptor... descriptors) {
+        snippets.add(requestHeaders(descriptors));
+        return this;
+    }
+
+    public RestDocsRequest requestCookie(CookieDescriptor... descriptors) {
+        snippets.add(requestCookies(descriptors));
+        return this;
+    }
+
+    public RestDocsRequest requestBodyField(FieldDescriptor... descriptors) {
+        snippets.add(requestFields(descriptors));
+        return this;
+    }
+
+    public ResourceSnippetParametersBuilder getResourceBuilder() {
+        return resourceBuilder;
+    }
+
+    public List<Snippet> getSnippets() {
+        return List.copyOf(snippets);
+    }
+}

src/test/java/baegam/sundae/document/RestDocsRequest.java

@@ -0,0 +1,40 @@
+package baegam.sundae.document;
+
+import static org.springframework.restdocs.cookies.CookieDocumentation.responseCookies;
+import static org.springframework.restdocs.headers.HeaderDocumentation.responseHeaders;
+import static org.springframework.restdocs.payload.PayloadDocumentation.responseFields;
+
+import java.util.LinkedList;
+import java.util.List;
+import org.springframework.restdocs.cookies.CookieDescriptor;
+import org.springframework.restdocs.headers.HeaderDescriptor;
+import org.springframework.restdocs.payload.FieldDescriptor;
+import org.springframework.restdocs.snippet.Snippet;
+
+public class RestDocsResponse {
+
+    private final List<Snippet> snippets;
+
+    public RestDocsResponse() {
+        this.snippets = new LinkedList<>();
+    }
+
+    public RestDocsResponse responseHeader(HeaderDescriptor... descriptors) {
+        snippets.add(responseHeaders(descriptors));
+        return this;
+    }
+
+    public RestDocsResponse responseCookie(CookieDescriptor... descriptors) {
+        snippets.add(responseCookies(descriptors));
+        return this;
+    }
+
+    public RestDocsResponse responseBodyField(FieldDescriptor... descriptors) {
+        snippets.add(responseFields(descriptors));
+        return this;
+    }
+
+    public List<Snippet> getSnippets() {
+        return List.copyOf(snippets);
+    }
+}

src/test/java/baegam/sundae/document/RestDocsResponse.java

@@ -0,0 +1,17 @@
+package baegam.sundae.document;
+
+public enum Tag {
+
+    MEMBER_API("Member API"), // Example (추후 삭제)
+    ;
+
+    private final String displayName;
+
+    Tag(String displayName) {
+        this.displayName = displayName;
+    }
+
+    public String getDisplayName() {
+        return displayName;
+    }
+}