Spring Rest Docs

build.gradle 설정

plugin

• gradle 7부터는 플러그인을 jvm을 사용하므로 org.asciidoctor.jvm.convert로 변경이 필요합니다.

• https://asciidoctor.github.io/asciidoctor-gradle-plugin/master/user-guide/

id "org.asciidoctor.jvm.convert" version "3.3.2"

dependency

• 기존에는 dependency를 asciidoctor로 사용하였으나 asciidoctorExt로 변경되었습니다.

asciidoctorExt 'org.springframework.restdocs:spring-restdocs-asciidoctor:2.0.6.RELEASE'

configurations

configurations {
    asciidoctorExt //asciidoc
}

• asciidoctorExt 를 configurations로 등록합니다.

asciidoctor

asciidoctor {
    configurations "asciidoctorExt"
    inProcess = JAVA_EXEC
    forkOptions {
        jvmArgs("--add-opens", "java.base/sun.nio.ch=ALL-UNNAMED", "--add-opens", "java.base/java.io=ALL-UNNAMED")
    }
    baseDirFollowsSourceFile()
    inputs.dir snippetsDir
    dependsOn test
}

asciidoctor.doFirst {
    delete file('src/main/resources/static/docs')
}

bootJar {
    dependsOn asciidoctor
    copy {
        from "${asciidoctor.outputDir}"
        into 'BOOT-INF/classes/static/docs'
    }
}

build {
    dependsOn copyDocument
}

• build시 html 파일이 resources/static에 복사되도록 하였습니다.
• 17버전의 경우 복사하는 과정에서 권한문제가 생겨 forkOptions를 통해 해결했습니다.
• 참고 : [Java 16] FilenoUtil : Native subprocess control requires open access to the JDK IO subsystem

Rest Docs 양식

ifndef::snippets[]
:snippets: ../../../build/generated-snippets
endif::[]
:doctype: book
:icons: font
:source-highlighter: highlightjs
:toc: left
:toclevels: 3
:sectlinks:
:docinfo: shared-head


== API

=== 공통

=== 기능

==== Request

===== Request HTTP Example

==== Response

===== Response HTTP Example

이미지 업로드 기능 Documentation

Spring REST Docs로 API 문서화하기 - woowa-turkey/miniprojects-2019 Wiki

참고: http://woowabros.github.io/experience/2018/12/28/spring-rest-docs.html 참고 2: https://spring.io/guides/gs/testing-restdocs/ Spring REST Docs는 Spring 프로젝트 중 API 문서를 만들도록 지원하는 프로젝트이다. 테스트 코드를 활용하여 문서화한다는 점이 큰 특징이다. REST Docs로 문서화할 때 Spring Web 테스트 객체인 MockMvc, RestAssured, WebTestClient 모두 문서화 할 수 있도록 지원한다. 이번 프로젝트에서는 WebTestClient를 기반으로 테스트를 작성하였으므로 WebTestClient를 통한 API 문서화를 알아본다.

https://github-wiki-see.page/m/woowa-turkey/miniprojects-2019/wiki/Spring-REST-Docs%EB%A1%9C-API-%EB%AC%B8%EC%84%9C%ED%99%94%ED%95%98%EA%B8%B0

Reference

Spring REST Docs

The aim of Spring REST Docs is to help you produce accurate and readable documentation for your RESTful services. Writing high-quality documentation is difficult. One way to ease that difficulty is to use tools that are well-suited to the job. To this end, Spring REST Docs uses Asciidoctor by default.

https://docs.spring.io/spring-restdocs/docs/current/reference/html5/

Spring Rest Docs 적용 | 우아한형제들 기술블로그

안녕하세요? 우아한형제들에서 정산시스템을 개발하고 있는 이호진입니다. 지금부터 정산시스템 API 문서를 wiki 에서 Spring Rest Docs 로 전환한 이야기를 해보려고 합니다. 현재 정산시스템은 API 문서를 wiki 로 공유하고 있었습니다. 며칠 전 API 에 필드를 추가하고 API 문서를 확인해보니 변경된 코드와 달랐습니다. 있어야 할 필드가 없었고 없어야 할 필드가 있었으며 같은 값을 주는 필드가 각기 다른이름의 필드로 제공되었습니다.

https://techblog.woowahan.com/2597/