CODEWITHSUNDEEP
spring-mvcspring-bootdocumentationspring-restdocs
Игорь Кравченко
Игорь Кравченко

Reputation: 43

Publish spring-restdocs html documentation with application

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.

Upvotes: 3

Views: 2557

Answers (3)

Java_Explorer
Java_Explorer

Reputation: 221

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>`

Upvotes: 1

hilbert
hilbert

Reputation: 266

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.

Upvotes: 0

Mykola Slutskyi
Mykola Slutskyi

Reputation: 168

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

Upvotes: 13

Related Questions