Merge pull request #132 from Menjil-Menjil/131-add-spring-rest-docs

131 add spring rest docs

build.gradle

@@ -5,8 +5,127 @@ plugins {
     id 'io.spring.dependency-management' version '1.0.15.RELEASE'
     id 'jacoco' // add jacoco plugin
     id 'com.google.osdetector' version "1.7.1" // https://github.com/netty/netty/issues/11020
+    id "org.asciidoctor.jvm.convert" version "3.3.2" // RestDocs
 }
 
+jar {
+    enabled = false
+}
+
+group = 'seoultech.capstone'
+version = '0.0.1-SNAPSHOT'
+sourceCompatibility = '11'
+
+configurations {
+    compileOnly {
+        extendsFrom annotationProcessor
+    }
+    asciidoctorExt // RestDocs
+}
+
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    if (osdetector.classifier == "osx-aarch_64") {
+        runtimeOnly("io.netty:netty-resolver-dns-native-macos:4.1.77.Final:${osdetector.classifier}")
+    }
+
+    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
+    implementation 'org.springframework.boot:spring-boot-starter-validation'
+    implementation 'org.springframework.boot:spring-boot-starter-web'
+
+    // parse json
+    implementation 'com.google.code.gson:gson:2.9.0'
+
+    // Security and OAuth
+//    implementation 'org.springframework.boot:spring-boot-starter-security'
+//    implementation 'org.springframework.boot:spring-boot-starter-oauth2-client'
+
+    // JWT
+    implementation group: 'io.jsonwebtoken', name: 'jjwt-api', version: '0.11.5'
+    runtimeOnly group: 'io.jsonwebtoken', name: 'jjwt-impl', version: '0.11.5'
+    runtimeOnly group: 'io.jsonwebtoken', name: 'jjwt-jackson', version: '0.11.5'
+
+    // chat-bot
+    implementation 'org.springframework.boot:spring-boot-starter-websocket'
+    implementation 'org.springframework.boot:spring-boot-starter-webflux'
+    implementation 'org.webjars:sockjs-client:1.1.2'
+    implementation 'org.webjars:stomp-websocket:2.3.3-1'
+
+    // AWS
+//    implementation platform('software.amazon.awssdk:bom:2.20.56') // 파일의 종속성 섹션에 BOM (재료 명세서) 을 추가합니다.
+//    implementation 'software.amazon.awssdk:s3' // 종속성 섹션에 사용할 SDK 모듈을 지정합니다(S3).
+    implementation group: 'io.awspring.cloud', name: 'spring-cloud-starter-aws', version: '2.4.2'
+
+    // lombok
+    compileOnly 'org.projectlombok:lombok'
+    annotationProcessor 'org.projectlombok:lombok'
+
+    // database
+    runtimeOnly 'com.mysql:mysql-connector-j'
+    implementation 'org.springframework.boot:spring-boot-starter-data-mongodb'
+
+    // RestDocs
+    asciidoctorExt 'org.springframework.restdocs:spring-restdocs-asciidoctor'
+    testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
+
+    testImplementation 'org.springframework.boot:spring-boot-starter-test'
+
+    // WireMock
+    testImplementation "com.github.tomakehurst:wiremock-jre8:2.35.0"
+    testImplementation "org.assertj:assertj-core:3.24.2"
+}
+
+tasks.named('test') {
+    useJUnitPlatform()
+    finalizedBy 'jacocoTestReport'
+}
+
+/* start RestDocs */
+ext { // 전역 변수
+    snippetsDir = file('build/generated-snippets')
+}
+
+test {
+    outputs.dir snippetsDir
+}
+
+asciidoctor.doFirst {
+    delete file('src/main/resources/static/docs')
+}
+
+asciidoctor {
+    inputs.dir snippetsDir
+    configurations 'asciidoctorExt'
+
+    sources { // 특정 파일만 html로 만든다.
+        include("**/index.adoc")
+    }
+    baseDirFollowsSourceFile() // 다른 adoc 파일을 include 할 때 경로를 baseDir로 맞춘다.
+    dependsOn test
+}
+
+bootJar {
+    dependsOn asciidoctor
+    from("${asciidoctor.outputDir}") {
+        into 'static/docs'
+    }
+}
+
+tasks.register('copyDocument', Copy) {
+    dependsOn asciidoctor
+    from file("build/docs/asciidoc")
+    into file("src/main/resources/static/docs")
+}
+
+build {
+    dependsOn copyDocument
+}
+/* end RestDocs */
+
+/* jacoco start */
 jacoco {
     toolVersion = '0.8.10'
 }
@@ -35,8 +154,7 @@ jacocoTestReport {
                     "seoultech/capstone/menjil/domain/chat/dto/**",
                     "seoultech/capstone/menjil/global/filter/*CustomCors*",
                     "**/*Config*",
-                    "**/*Exception*",
-                    "**/TokenTestController*"
+                    "**/*Exception*"
             ])
         }))
     }
@@ -50,7 +168,7 @@ jacocoTestCoverageVerification {
             enabled = true
             limit {
                 value = 'COVEREDRATIO'
-                minimum = 0.50
+                minimum = 0.05
             }
             excludes = [
                     "**.*jilApplication*",
@@ -61,8 +179,7 @@ jacocoTestCoverageVerification {
                     "**/domain/chat/dto/**",
                     "**.*Config*",
                     "**.*CustomCors*",
-                    "**.*Exception*",
-                    "**.TokenTestController*"
+                    "**.*Exception*"
             ]
         }
 
@@ -83,77 +200,6 @@ jacocoTestCoverageVerification {
 
     }
 }
-
-jar {
-    enabled = false
-}
-
-group = 'seoultech.capstone'
-version = '0.0.1-SNAPSHOT'
-sourceCompatibility = '11'
-
-configurations {
-    compileOnly {
-        extendsFrom annotationProcessor
-    }
-}
-
-repositories {
-    mavenCentral()
-}
-
-dependencies {
-    if (osdetector.classifier == "osx-aarch_64") {
-        runtimeOnly("io.netty:netty-resolver-dns-native-macos:4.1.77.Final:${osdetector.classifier}")
-    }
-
-    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
-    implementation 'org.springframework.boot:spring-boot-starter-validation'
-    implementation 'org.springframework.boot:spring-boot-starter-web'
-
-    // parse json
-    implementation 'com.google.code.gson:gson:2.9.0'
-
-    // Security and OAuth
-//    implementation 'org.springframework.boot:spring-boot-starter-security'
-//    implementation 'org.springframework.boot:spring-boot-starter-oauth2-client'
-
-    // JWT
-    implementation group: 'io.jsonwebtoken', name: 'jjwt-api', version: '0.11.5'
-    runtimeOnly group: 'io.jsonwebtoken', name: 'jjwt-impl', version: '0.11.5'
-    runtimeOnly group: 'io.jsonwebtoken', name: 'jjwt-jackson', version: '0.11.5'
-
-    // chat-bot
-    implementation 'org.springframework.boot:spring-boot-starter-websocket'
-    implementation 'org.springframework.boot:spring-boot-starter-webflux'
-    implementation 'org.webjars:sockjs-client:1.1.2'
-    implementation 'org.webjars:stomp-websocket:2.3.3-1'
-
-    // AWS
-//    implementation platform('software.amazon.awssdk:bom:2.20.56') // 파일의 종속성 섹션에 BOM (재료 명세서) 을 추가합니다.
-//    implementation 'software.amazon.awssdk:s3' // 종속성 섹션에 사용할 SDK 모듈을 지정합니다(S3).
-    implementation group: 'io.awspring.cloud', name: 'spring-cloud-starter-aws', version: '2.4.2'
-
-    // lombok
-    compileOnly 'org.projectlombok:lombok'
-    annotationProcessor 'org.projectlombok:lombok'
-
-    // database
-    runtimeOnly 'com.mysql:mysql-connector-j'
-    implementation 'org.springframework.boot:spring-boot-starter-data-mongodb'
-//    testImplementation 'de.flapdoodle.embed:de.flapdoodle.embed.mongo'
-
-    testImplementation 'org.springframework.boot:spring-boot-starter-test'
-//    testImplementation 'com.squareup.okhttp3:mockwebserver:4.10.0'
-
-    // WireMock
-    testImplementation "com.github.tomakehurst:wiremock-jre8:2.35.0"
-    testImplementation "org.assertj:assertj-core:3.24.2"
-}
-
-tasks.named('test') {
-    useJUnitPlatform()
-    finalizedBy 'jacocoTestReport'
-}
+/* jacoco end */
 
 mainClassName = 'seoultech.capstone.menjil.MenjilApplication'

src/docs/asciidoc/index.adoc

@@ -0,0 +1,145 @@
+// ifndef::snippets[]
+// = :snippets: ../../build/generated-snippets
+// endif::[]
+= 멘질멘질 REST API 문서
+:doctype: book
+:icons: font
+:source-highlighter: highlightjs
+:toc: left
+:toclevels: 2
+:sectlinks:
+:sectnums:
+
+== 회원가입
+
+=== 이메일 중복 확인
+==== 성공
+===== 회원가입이 가능한 경우
+요청한 이메일이 가입되어있지 않은 경우
+
+operation::api/auth/signup-is-available/true[snippets='http-request,request-parameters']
+operation::api/auth/signup-is-available/true[snippets='http-response,response-fields']
+
+==== 실패
+===== 회원가입이 불가능한 경우
+요청한 이메일이 이미 가입되어있는 경우
+
+operation::api/auth/signup-is-available/false[snippets='http-request']
+operation::api/auth/signup-is-available/false[snippets='http-response']
+
+=== 닉네임 중복 확인
+
+==== 성공
+===== 사용할 수 있는 닉네임 형식인 경우
+operation::api/auth/check-nickname/true[snippets='http-request,request-parameters']
+operation::api/auth/check-nickname/true[snippets='http-response,response-fields']
+
+==== 실패
+===== 닉네임에 공백이 포함된 경우
+operation::api/auth/check-nickname/false-blank[snippets='http-request']
+operation::api/auth/check-nickname/false-blank[snippets='http-response']
+
+===== 닉네임에 특수문자가 포함된 경우
+operation::api/auth/check-nickname/false-special-character[snippets='http-request']
+operation::api/auth/check-nickname/false-special-character[snippets='http-response']
+
+===== 닉네임이 이미 사용 중인 경우(존재하는 경우)
+operation::api/auth/check-nickname/false-conflict[snippets='http-request']
+operation::api/auth/check-nickname/false-conflict[snippets='http-response']
+
+
+=== 회원 가입
+
+==== 성공
+operation::api/auth/signup/true[snippets='http-request,request-fields']
+operation::api/auth/signup/true[snippets='http-response,response-fields']
+
+==== 실패
+===== 닉네임에 공백이 포함되어 있는 경우
+operation::api/auth/signup/false-blank[snippets='http-request']
+operation::api/auth/signup/false-blank[snippets='http-response']
+
+===== 닉네임에 특수문자가 포함되어 있는 경우
+operation::api/auth/signup/false-special-character[snippets='http-request']
+operation::api/auth/signup/false-special-character[snippets='http-response']
+
+===== 닉네임에 null 값이 들어온 경우
+operation::api/auth/signup/false-null[snippets='http-request']
+operation::api/auth/signup/false-null[snippets='http-response']
+
+===== 학점이 4 초과한 값이 들어온 경우
+operation::api/auth/signup/false-score-max[snippets='http-request']
+operation::api/auth/signup/false-score-max[snippets='http-response']
+
+
+
+
+== 로그인
+=== 로그인
+==== 성공
+operation::api/auth/signin/success[snippets='http-request,request-fields']
+operation::api/auth/signin/success[snippets='http-response,response-fields']
+
+==== 실패
+===== 플랫폼이 google, kakao 가 아닌 경우
+operation::api/auth/signin/fail-provider[snippets='http-request']
+operation::api/auth/signin/fail-provider[snippets='http-response']
+
+
+// ** 2. 팔로우 **
+== 팔로우
+=== 팔로우 요청
+==== 팔로우가 되어있지 않은 경우
+팔로우가 생성된다.
+
+operation::api/follow/create/201/true[snippets='http-request,request-fields']
+operation::api/follow/create/201/true[snippets='http-response,response-fields']
+
+==== 이미 팔로우가 되어 있는 경우
+팔로우가 해제된다.
+
+operation::api/follow/create/201/false[snippets='http-request,request-fields']
+operation::api/follow/create/201/false[snippets='http-response,response-fields']
+
+==== 서버 오류
+
+operation::api/follow/create/500[snippets='http-request,request-fields']
+operation::api/follow/create/500[snippets='http-response,response-fields']
+
+=== 팔로우 상태 확인
+
+==== 팔로우가 되어있는 경우
+return true
+
+operation::api/follow/check-status/true[snippets='http-request,request-parameters']
+operation::api/follow/check-status/true[snippets='http-response,response-fields']
+
+==== 팔로우가 되어있지 않은 경우
+return false
+
+operation::api/follow/check-status/false[snippets='http-request,request-parameters']
+operation::api/follow/check-status/false[snippets='http-response,response-fields']
+
+
+
+// ** 3. 팔로잉 페이지 **
+== 팔로잉
+=== 니의 팔로잉 목록 가져오기
+
+
+
+=== 팔로잉된 사용자의 상세 정보 조회
+==== 성공
+===== 사용자의 정보와 질문 답변 내역이 모두 존재하는 경우
+operation::api/following/info/200-ok[snippets='http-request,request-parameters']
+operation::api/following/info/200-ok[snippets='http-response,response-fields']
+
+===== 사용자의 정보만 존재하는 경우
+operation::api/following/info/200-only-userinfo[snippets='http-request']
+operation::api/following/info/200-only-userinfo[snippets='http-response']
+
+==== 실패
+===== 존재하지 않는 사용자의 닉네임을 요청한 경우
+operation::api/following/info/500-error[snippets='http-request']
+operation::api/following/info/500-error[snippets='http-response,response-fields']
+

src/main/java/seoultech/capstone/menjil/MenjilApplication.java

@@ -2,9 +2,7 @@
 
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
-import org.springframework.data.jpa.repository.config.EnableJpaAuditing;
 
-@EnableJpaAuditing
 @SpringBootApplication
 public class MenjilApplication {