add : api document 기초 세팅

.gitignore

@@ -40,4 +40,9 @@ out/
 .env
 
 ### sql ###
-*.sql
+*.sql
+
+### api docs ###
+src/main/resources/static/docs/openapi3.yaml
+src/main/resources/static/docs/index.html
+src/docs/asciidoc/index.html

build.gradle

@@ -28,10 +28,6 @@ repositories {
     mavenCentral()
 }
 
-ext {
-    set('snippetsDir', file("build/generated-snippets"))
-}
-
 dependencies {
     implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
     implementation 'org.springframework.boot:spring-boot-starter-web'
@@ -67,7 +63,6 @@ dependencies {
     // Document
     testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
     asciidoctorExt 'org.springframework.restdocs:spring-restdocs-asciidoctor'
-    testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
     testImplementation 'com.epages:restdocs-api-spec-mockmvc:0.18.2'
     testImplementation 'com.epages:restdocs-api-spec-restassured:0.18.2'
     testImplementation 'org.springframework.restdocs:spring-restdocs-restassured'
@@ -77,14 +72,25 @@ dependencies {
     testImplementation 'org.springframework.boot:spring-boot-starter-test'
     testImplementation 'org.springframework.security:spring-security-test'
     testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
+
 }
 
 tasks.named('test') {
     delete file('build/generated-snippets')
-    outputs.dir snippetsDir
     useJUnitPlatform()
 }
 
+openapi3 {
+    servers = [
+            { url = "http://localhost:8080/" },
+            { url = "https://dev-api.fittheman.site/" }
+    ]
+    title = '핏더맨 API DOCUMENT'
+    description = '핏더맨 api 명세서입니다.'
+    version = '0.1.0'
+    format = 'yaml'
+}
+
 tasks.named('asciidoctor') {
     inputs.dir snippetsDir
     dependsOn test
@@ -112,36 +118,30 @@ tasks.register('copyOasToSwagger', Copy) {
 
     // openapi3 task가 먼저 실행되도록 설정
     dependsOn tasks.named('openapi3')
+
+    dependsOn tasks.named('addAuthorization')
 }
 
-tasks.withType(GenerateSwaggerUI) {
+
+
+tasks.register('addAuthorization', Task) {
     dependsOn 'openapi3'
-    doFirst {
+    doLast {
         def swaggerUIFile = file("${openapi3.outputDirectory}/openapi3.yaml")
 
-        def securitySchemesContent =  "  securitySchemes:\n" +  \
-                                      "    APIKey:\n" +  \
-                                      "      type: apiKey\n" +  \
-                                      "      name: Authorization\n" +  \
-                                      "      in: header\n" + \
-                                      "security:\n" +
+        println("swaggerUIFile 경로: ${swaggerUIFile}")
+        def securitySchemesContent =  "  securitySchemes:\n" +
+                "    APIKey:\n" +
+                "      type: apiKey\n" +
+                "      name: JSESSIONID\n" +
+                "      in: cookie\n" +
+                "security:\n" +
                 "  - APIKey: []  # Apply the security scheme here"
 
         swaggerUIFile.append securitySchemesContent
     }
 }
 
-openapi3 {
-    servers = [
-            { url = "http://localhost:8080/" },
-            { url = "https://dev-api.fittheman.site/" }
-    ]
-    title = '핏더맨 API DOCUMENT'
-    description = '핏더맨 api 명세서입니다.'
-    version = '0.1.0'
-    format = 'yaml'
-}
-
 jar.enabled = false
 
 spotless {

src/docs/asciidoc/index.adoc

@@ -0,0 +1,101 @@
+:doctype: book
+:toc: left
+:icons: font
+:toclevels: 3
+:source-highlighter: highlightjs
+:sectlinks:
+
+= **FitTheMan API Document**
+
+
+== 문서
+[cols="2,4,4", options="header"]
+|===
+| Name |Url| 비고
+| Rest Docs |/docs/index.html| 기본 API 문서
+| API Test |/docs/swagger-ui.html| Swagger Api Test 문서
+|===
+
+== API 서버 경로
+[cols="2,4,4",options="header"]
+|===
+| 환경 | 도메인 | 비고
+| 개발(dev) | https://dev-api.fittheman.site | API 문서 제공
+|===
+
+== 응답형식
+
+=== 공통 응답 형식
+
+[source, json]
+----
+HTTP/1.1 {HTTP STATUS CODE} {HTTP STATUS}
+Content-Type : application/json
+{
+  "status":  "http status" ,
+  "code":  "custom status code",
+  "message" : "response message"
+  "data": "data"
+}
+----
+
+=== 성공 응답
+
+요청이 성공했을 경우 아래의 Http Status 중 하나를 반환합니다.
+
+[cols="5,5,10,6", options="header"]
+|===
+| Http Status Code | Http Status | 비고 | Response Body
+| 200 | OK | 요청에 성공  | O
+| 201 | CREATED | resource 생성 | O
+| 203 | ACCEPTED | 요청은 수락되었지만 아직 처리가 완료되지 않음 | O
+| 204 | NO CONTENT |요청에 성공했으나 반환할 응답값이 없음 | X
+|===
+
+=== 응답 예시
+
+==== 1. Response Body가 없는 경우
+
+[source, json]
+----
+HTTP/1.1 204 NO CONTENT
+----
+
+==== 2. 응답 data가 없는 경우
+[source, json]
+----
+HTTP/1.1 201 CREATED
+Content-Type: application/json
+{
+  "status": "CREATED", // 예시
+  "code": "S002", //예시
+  "message" : "resource가 정상적으로 생성되었습니다."
+  "data": null
+}
+----
+
+==== 3. 응답 data가 있는 경우 예시
+[source, json]
+----
+HTTP/1.1 200 OK
+Content-Type: application/json
+{
+  "status": "OK", //예시
+  "code": "S001", //예시
+  "message" : "요청이 정상적으로 처리되었습니다."
+  "data": {
+    "id": 123,
+    "name": "example"
+  }
+}
+----
+
+== 실패 응답
+
+[cols="2,4,4,4,8", options="header"]
+|===
+| 구분 |Http Status Code | Http Status  | custom error code | 비고
+| 공통 | 400 | BAD_REQUEST | E400_001 | API 요청에 요구되는 request의 모든 조건을 만족하지 못했을 경우 공통적으로 반환됨. (ex.email 형식 불일치, request parameter 누락, 필드 type 불일치)
+| 공통 | 500 | INTERNAL_SERVER_ERROR | E500_001 | 서버 측에서 처리하지 못한 예외가 발생하면 모든 api 요청에 대해 공통적으로 반환됨.
+|===
+

src/main/resources/static/docs/index.css

@@ -1,16 +1,16 @@
-html {
-    box-sizing: border-box;
-    overflow: -moz-scrollbars-vertical;
-    overflow-y: scroll;
-}
-
-*,
-*:before,
-*:after {
-    box-sizing: inherit;
-}
-
-body {
-    margin: 0;
-    background: #fafafa;
-}
+html {
+    box-sizing: border-box;
+    overflow: -moz-scrollbars-vertical;
+    overflow-y: scroll;
+}
+
+*,
+*:before,
+*:after {
+    box-sizing: inherit;
+}
+
+body {
+    margin: 0;
+    background: #fafafa;
+}

src/main/resources/static/docs/swagger-initializer.js

@@ -1,20 +1,20 @@
-window.onload = function() {
-  //<editor-fold desc="Changeable Configuration Block">
-
-  // the following lines will be replaced by docker/configurator, when it runs in a docker-container
-  window.ui = SwaggerUIBundle({
-    url: "openapi3.yaml",
-    dom_id: '#swagger-ui',
-    deepLinking: true,
-    presets: [
-      SwaggerUIBundle.presets.apis,
-      SwaggerUIStandalonePreset
-    ],
-    plugins: [
-      SwaggerUIBundle.plugins.DownloadUrl
-    ],
-    layout: "StandaloneLayout"
-  });
-
-  //</editor-fold>
-};
+window.onload = function() {
+  //<editor-fold desc="Changeable Configuration Block">
+
+  // the following lines will be replaced by docker/configurator, when it runs in a docker-container
+  window.ui = SwaggerUIBundle({
+    url: "openapi3.yaml",
+    dom_id: '#swagger-ui',
+    deepLinking: true,
+    presets: [
+      SwaggerUIBundle.presets.apis,
+      SwaggerUIStandalonePreset
+    ],
+    plugins: [
+      SwaggerUIBundle.plugins.DownloadUrl
+    ],
+    layout: "StandaloneLayout"
+  });
+
+  //</editor-fold>
+};

src/main/resources/static/docs/swagger-ui.html

@@ -1,19 +1,19 @@
-<!-- HTML for static distribution bundle build -->
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8">
-    <title>Swagger UI</title>
-    <link rel="stylesheet" type="text/css" href="./swagger-ui.css" />
-    <link rel="stylesheet" type="text/css" href="index.css" />
-    <link rel="icon" type="image/png" href="./favicon-32x32.png" sizes="32x32" />
-    <link rel="icon" type="image/png" href="./favicon-16x16.png" sizes="16x16" />
-  </head>
-
-  <body>
-    <div id="swagger-ui"></div>
-    <script src="./swagger-ui-bundle.js" charset="UTF-8"> </script>
-    <script src="./swagger-ui-standalone-preset.js" charset="UTF-8"> </script>
-    <script src="./swagger-initializer.js" charset="UTF-8"> </script>
-  </body>
-</html>
+<!-- HTML for static distribution bundle build -->
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <title>Swagger UI</title>
+    <link rel="stylesheet" type="text/css" href="./swagger-ui.css" />
+    <link rel="stylesheet" type="text/css" href="index.css" />
+    <link rel="icon" type="image/png" href="./favicon-32x32.png" sizes="32x32" />
+    <link rel="icon" type="image/png" href="./favicon-16x16.png" sizes="16x16" />
+  </head>
+
+  <body>
+    <div id="swagger-ui"></div>
+    <script src="./swagger-ui-bundle.js" charset="UTF-8"> </script>
+    <script src="./swagger-ui-standalone-preset.js" charset="UTF-8"> </script>
+    <script src="./swagger-initializer.js" charset="UTF-8"> </script>
+  </body>
+</html>

src/test/resources/application-test.yml

@@ -21,7 +21,7 @@ spring:
 
   sql:
     init:
-      mode: always
+      mode: never
       schema-locations: classpath:test-schema.sql
       data-locations: classpath:test-data.sql
 

src/test/resources/org/springframework/restdocs/templates/asciidoctor/query-parameters.snippet

@@ -0,0 +1,12 @@
+|===
+|Parameter|Description|Required|Default
+
+{{#parameters}}
+    |{{#tableCellContent}}`+{{name}}+`{{/tableCellContent}}
+    |{{#tableCellContent}}{{description}}{{/tableCellContent}}
+    |{{#tableCellContent}}{{#optional}}false{{/optional}}{{^optional}}true{{/optional}}{{/tableCellContent}}
+    |{{#tableCellContent}}{{#default}}{{default}}{{/default}}{{^default}} {{/default}}{{/tableCellContent}}
+
+
+{{/parameters}}
+|===

src/test/resources/org/springframework/restdocs/templates/asciidoctor/request-fields.snippet

@@ -0,0 +1,10 @@
+|===
+|Path|Type|Description|Required|Constraint
+{{#fields}}
+    |{{#tableCellContent}}`+{{path}}+`{{/tableCellContent}}
+    |{{#tableCellContent}}`+{{type}}+`{{/tableCellContent}}
+    |{{#tableCellContent}}{{description}}{{/tableCellContent}}
+    |{{#tableCellContent}}{{^optional}}true{{/optional}}{{#optional}}false{{/optional}}{{/tableCellContent}}
+    |{{#tableCellContent}}{{#constraint}}{{constraint}}{{/constraint}}{{^constraint}} {{/constraint}}{{/tableCellContent}}
+{{/fields}}
+|===

src/test/resources/org/springframework/restdocs/templates/asciidoctor/request-part-fields.snippet

@@ -0,0 +1,12 @@
+|===
+|Path|Type|Description|Required|Constraint
+
+{{#fields}}
+|{{#tableCellContent}}`+{{path}}+`{{/tableCellContent}}
+|{{#tableCellContent}}`+{{type}}+`{{/tableCellContent}}
+|{{#tableCellContent}}{{description}}{{/tableCellContent}}
+|{{#tableCellContent}}{{^optional}}true{{/optional}}{{#optional}}false{{/optional}}{{/tableCellContent}}
+|{{#tableCellContent}}{{#constraint}}{{constraint}}{{/constraint}}{{^constraint}} {{/constraint}}{{/tableCellContent}}
+
+{{/fields}}
+|===

src/test/resources/org/springframework/restdocs/templates/asciidoctor/request-parts.snippet

@@ -0,0 +1,11 @@
+
+**content-type : multipart/form-data**
+|===
+|Name|Description|Content-Type
+
+{{#requestParts}}
+    |{{#tableCellContent}}`+{{name}}+`{{/tableCellContent}}
+    |{{#tableCellContent}}{{description}}{{/tableCellContent}}
+    |{{#tableCellContent}}{{#content-type}}{{content-type}}{{/content-type}}{{^content-type}} {{/content-type}}{{/tableCellContent}}
+{{/requestParts}}
+|===

src/test/resources/org/springframework/restdocs/templates/asciidoctor/response-fields.snippet

@@ -0,0 +1,10 @@
+|===
+|Path|Type|Description|Nullable
+
+{{#fields}}
+    |{{#tableCellContent}}`+{{path}}+`{{/tableCellContent}}
+    |{{#tableCellContent}}`+{{type}}+`{{/tableCellContent}}
+    |{{#tableCellContent}}{{description}}{{/tableCellContent}}
+    |{{#tableCellContent}}{{#nullable}}{{nullable}}{{/nullable}}{{^nullable}} {{/nullable}}{{/tableCellContent}}
+{{/fields}}
+|===