spring-asciidoctor-extensions 사용해 보기

Spring은 asciidoctor 문서 작성을 위해 spring-doc-resource와 함께 spring-asciidoctor-extensions를 제공하고 있다.

이전에 spring-doc-resource에 대해 소개한 적이 있다.

2020/06/12 - [Study/Java] - spring reference 문서는 어떻게 만들어질까?

spring reference 문서는 어떻게 만들어질까?

spring-doc-resource로 spring reference 문서의 스타일이 제공되고 spring-asciidoctor-extension을 통해 아래의 기능이 제공되고 있다.

• Block Switch - 문서의 예제에 탭을 추가하여 스위칭할 수 있도록 하는 기능 제공 (Spring Framework reference의 예제 참고)
  
  
• configprop - 스프링 속성 값에 대한 검증 기능 제공
• configblocks - yaml source만 명시해도 properties source를 block switch로 제공 (0.5.0 이후 제공)

block switch - Java/Kotlin 예제를 탭을 선택해 스위칭 할 수 있다.

설정하기

spring-asciidoctor-extensions를 사용하려면 우선 spring-doc-resource까지의 설정이 선행되어야 한다.

위에 글을 참고하면 된다.

spring-asciidoctor-extensions는 maven plugin이지만 maven central 에는 없다.

따라서 아래처럼 pluginRepository 설정을 추가해야 한다.

<pluginRepositories>
    <pluginRepository>
        <id>spring-snapshots</id>
        <url>http://repo.spring.io/snapshot</url>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </pluginRepository>
    <pluginRepository>
        <id>spring-milestones</id>
        <url>http://repo.spring.io/milestone</url>
    </pluginRepository>
    <pluginRepository>
        <id>spring-releases</id>
        <url>https://repo.spring.io/release</url>
    </pluginRepository>
</pluginRepositories>

기존 asciidoctor-maven-plugin 설정에 spring-asciidoctor-extension 설정을 추가한다.

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>${asciidoctor.maven.plugin.version}</version>
    <dependencies>
        <dependency>
            <groupId>org.springframework.restdocs</groupId>
            <artifactId>spring-restdocs-asciidoctor</artifactId>
            <version>${spring-restdocs.version}</version>
        </dependency>
        <dependency>
            <groupId>io.spring.asciidoctor</groupId>
            <artifactId>spring-asciidoctor-extensions-block-switch</artifactId>
            <version>${spring-asciidoctor-extensions.version}</version>
        </dependency>
        <dependency>
            <groupId>io.spring.asciidoctor</groupId>
            <artifactId>spring-asciidoctor-extensions-spring-boot</artifactId>
            <version>${spring-asciidoctor-extensions.version}</version>
        </dependency>
    </dependencies>
    <executions>
        <execution>
            <id>asciidoc-to-html</id>
            <phase>prepare-package</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                // .. 기존 설정 유지
            </configuration>
        </execution>
    </executions>
</plugin>

위처럼 설정하면 spring asciidoctor extension을 사용할 수 있게 된다.

개인적으로 테스트해보니 block switch는 잘 동작하는데 spring boot의 configprop는 죄다 없다고 warning이 뜬다.

아직 이 부분에 대해서는 원인이 무엇인지 찾지 못하였다.