[SpringBoot] API 문서화 세팅 (asciidoctor)

Test 케이스 작성

테스트 케이스 작성 설명 링크 : https://radpro.tistory.com/285

---

index.adoc 작성

1. src 디렉토리안에 docs/asciidoc 경로 생성

2. index.adoc 파일 생성

3. 문서화 작성 방법 링크 : https://radpro.tistory.com/286

4. 작성 방법 예시

= stackOverFlow_Clone
:sectnums:
:toc: left
:toclevels: 4
:toc-title: Table of Contents
:source-highlighter: prettify

lastModified: 2022.10.28


***
== AccountController
=== Account 로그인
.curl-request
include::{snippets}/loginAccount/curl-request.adoc[]

.http-request
include::{snippets}/loginAccount/http-request.adoc[]

.request-fields
include::{snippets}/loginAccount/request-fields.adoc[]

.http-response
include::{snippets}/loginAccount/http-response.adoc[]

.response-headers
include::{snippets}/loginAccount/response-headers.adoc[]

.response-fields
include::{snippets}/loginAccount/response-fields.adoc[]

***
=== Account 생성
.curl-request
include::{snippets}/createAccount/curl-request.adoc[]

.http-request
include::{snippets}/createAccount/http-request.adoc[]

.request-parts
include::{snippets}/createAccount/request-parts.adoc[]

.request-parameters
include::{snippets}/createAccount/request-parameters.adoc[]

.http-response
include::{snippets}/createAccount/http-response.adoc[]

.response-fields
include::{snippets}/createAccount/response-fields.adoc[]

 

 

 

---

index.html 빌드

gradle 설정 > 그래들 업데이트 > 그래들 > bootjar

plugins {
 	...
    id "org.asciidoctor.jvm.convert" version "3.3.2"
    ...
}

ext {
    set('snippetsDir', file("build/generated-snippets"))
}

configurations {
    asciidoctorExtensions
    ...
}

dependencies {
    asciidoctorExtensions 'org.springframework.restdocs:spring-restdocs-asciidoctor'
}
tasks.named('test') {
    outputs.dir snippetsDir                      // 테스트 케이스 작성 후 완료되면 문서 저장경로
    useJUnitPlatform()
}

tasks.named('asciidoctor') {
    configurations "asciidoctorExtensions"     
    inputs.dir snippetsDir                       // build/snippet 안에 있는 문서를 참조한다는 의미 
    dependsOn test
}

task copyDocument(type: Copy) {
    dependsOn asciidoctor
    from file("${asciidoctor.outputDir}")        // index/adoc에서 include::{snippet}으로로 지정한 경로
    into file("src/main/resources/static/docs")  // index.html을 저장할 경로
}

build {
    dependsOn copyDocument
}

bootJar {
    dependsOn copyDocument
    from ("${asciidoctor.outputDir}") {
        into 'static/docs'                       // bootjar로 빌드시, index.html 저장 경로
    }
}

전체 설정

plugins {
    id 'org.springframework.boot' version '2.7.5'
    id 'io.spring.dependency-management' version '1.0.15.RELEASE'
    id "org.asciidoctor.jvm.convert" version "3.3.2"
    id 'java'
}

group = 'stackoverflow'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '11'

ext {
    set('snippetsDir', file("build/generated-snippets"))
}

configurations {
    asciidoctorExtensions
    compileOnly {
        extendsFrom annotationProcessor
    }
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-security'
    implementation 'org.springframework.boot:spring-boot-starter-validation'
    implementation 'com.github.gavlyukovskiy:p6spy-spring-boot-starter:1.8.0'
    implementation 'org.springframework.boot:spring-boot-starter-aop'
    implementation group: 'com.google.code.gson', name: 'gson'
    implementation 'org.springframework.cloud:spring-cloud-starter-aws:2.2.6.RELEASE'
    implementation 'io.jsonwebtoken:jjwt-api:0.11.5'
    runtimeOnly 'io.jsonwebtoken:jjwt-impl:0.11.5'
    runtimeOnly 'io.jsonwebtoken:jjwt-jackson:0.11.5'
    compileOnly 'org.projectlombok:lombok'
    runtimeOnly 'com.mysql:mysql-connector-j'
    annotationProcessor 'org.projectlombok:lombok'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    testImplementation 'org.springframework.security:spring-security-test'
    testImplementation 'com.h2database:h2:1.4.199'
    testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
    asciidoctorExtensions 'org.springframework.restdocs:spring-restdocs-asciidoctor'
}

tasks.named('test') {
    outputs.dir snippetsDir
    useJUnitPlatform()
}

tasks.named('asciidoctor') {
    configurations "asciidoctorExtensions"
    inputs.dir snippetsDir
    dependsOn test
}

task copyDocument(type: Copy) {
    dependsOn asciidoctor
    from file("${asciidoctor.outputDir}")
    into file("src/main/resources/static/docs")
}

build {
    dependsOn copyDocument
}

bootJar {
    dependsOn copyDocument
    from ("${asciidoctor.outputDir}") {
        into 'static/docs'
    }
}