使用应用程序发布 spring-restdocs html 文档

Question

我有 spring-boot 应用程序和 spring-restdocs，我想在该应用程序中为生成的文档创建端点。使用生成的 html 文档（由 asciidoctor）公开端点的最佳方法是什么？

我可以将 index.html 包含到 jar 文件中，但我真的不知道如何创建将使用 html 并公开 outside.This html 之后生成的端点测试阶段和构建 jar 阶段之前。

来自官方文档：您可以将您创建的 HTML 文档发布到静态网站，或者将其打包并从应用程序本身提供。

例如我在 'build/asctiidoctor/html5' 文件夹中有 index.html，我想创建控制器 return index.html。

Answer 1

根据documentation，您可以配置构建系统（Maven，Gradle）将HTML作为静态内容打包到spring-boot jar中，以便提供服务通过 Spring 启动 'automagically'

在 Gradle 4.6 和 Spring Boot 2.0 的情况下。0.RELEASE:

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

然后可以通过'localhost:<your-port>/<your-context-path/docs/index.html

本地验证

Answer 2

从 AsciiDoc 生成 html 后，只需将 html 文件复制到 target/generated-docs（参见 https://spring.io/guides/gs/testing-restdocs/）。 Spring-然后启动将在端点 <...>/docs/index.html.

中获取并托管文档

您可以 maven-resources-plugin 完成这项工作。

Answer 3

要使用 spring 在本地访问 api 指南，使用 url http://localhost:8081/docs/api-guide.html 引导，添加以下插件：

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

使用应用程序发布 spring-restdocs html 文档

Publish spring-restdocs html documentation with application

documentation

spring-mvc

spring-boot

spring-restdocs