Publish spring-restdocs html documentation with application

Question

I have spring-boot application with spring-restdocs and I want to create endpoint in that application for generated documentation. What is the best approach to expose endpoint with generated html documentation(by asciidoctor)?

I can include index.html to jar-file but don't really know how to create endpoint that will consume that html and expose outside.This html generated after test-stage and before build-jar-stage.

From official documentation: You could publish the HTML documentation you created to a static website, or package it up and serve it from the application itself.

e.g. I have index.html in 'build/asctiidoctor/html5' folder and want to create controller that will return that index.html.

score 12 · Accepted Answer · edited Mar 29 '18 at 16:30

12

According to documentation you can configure your build system (Maven, Gradle) to package HTML into spring-boot jar as static content so that it will be served by Spring Boot 'automagically'

In case of Gradle 4.6 and Spring Boot 2.0.0.RELEASE:

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

Then it can be verified locally via 'localhost:<your-port>/<your-context-path/docs/index.html

edited Mar 29 '18 at 16:30

glennsl

28,186
12
57
75

answered Mar 29 '18 at 16:20

Mykola Slutskyi

158
2
7

I don't catch how to access static context. Should URL be like **localhost:8080/docs/index.html**? – Игорь Кравченко Mar 30 '18 at 12:24
@ИгорьКравченко, yes something like this. Keep in mind, you have to prepend 'docs/index.html' to base path that is common to all api endpoints of your application. – Mykola Slutskyi Mar 30 '18 at 15:33
to access the api guide locally using spring boot, add the following: – Java_Explorer Nov 03 '20 at 10:30

score 1 · Answer 2 · answered Nov 03 '20 at 10:40

To access the api guide locally using spring boot using the url http://localhost:8081/docs/api-guide.html , add the following plugins:

           <plugin>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctor-maven-plugin</artifactId>
            <version>${asciidoctor-maven-plugin.version}</version>
            <executions>
                <execution>
                    <id>generate-docs</id>
                    <phase>post-integration-test</phase>
                    <goals>
                        <goal>process-asciidoc</goal>
                    </goals>
                    <configuration>
                        <backend>html</backend>
                        <doctype>book</doctype>
                    </configuration>
                </execution>
            </executions>
            <dependencies>
                <dependency>
                    <groupId>org.springframework.restdocs</groupId>
                    <artifactId>spring-restdocs-asciidoctor</artifactId>
                    <version>${spring-restdocs.version}</version>
                </dependency>
            </dependencies>
        </plugin>

        <plugin>
            <artifactId>maven-resources-plugin</artifactId>
            <version>${maven-resources-plugin.version}</version>
            <executions>
                <execution>
                    <id>copy-resources</id>
                    <phase>post-integration-test</phase>
                    <goals>
                        <goal>copy-resources</goal>
                    </goals>
                    <configuration>
                        <outputDirectory>
                            ${project.build.outputDirectory}/static/docs
                        </outputDirectory>
                        <resources>
                            <resource>
                                <directory>
                                    ${project.build.directory}/generated-docs
                                </directory>
                            </resource>
                        </resources>
                    </configuration>
                </execution>
            </executions>
        </plugin>`

This doesn't work. Do you have surefire or failsafe plugins to run integration tests? Can you share the full POM? — Shehan Simen, Feb 23 '21 at 06:41

score 0 · Answer 3 · answered Oct 22 '19 at 12:28

After generating html out of the AsciiDoc just copy the html files into target/generated-docs (see https://spring.io/guides/gs/testing-restdocs/). Spring-Boot then will take and host the documentation within the endpoint <...>/docs/index.html.

You could use maven-resources-plugin for this job.

Publish spring-restdocs html documentation with application

3 Answers3