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

【问题标题】：Publish spring-restdocs html documentation with application使用应用程序发布 spring-restdocs html 文档
【发布时间】：2018-03-29 14:03:52
【问题描述】：

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

我可以将 index.html 包含到 jar 文件中，但我真的不知道如何创建将使用该 html 并在外部公开的端点。此 html 在测试阶段之后和 build-jar-stage 之前生成。

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

例如我在“build/asctiidoctor/html5”文件夹中有 index.html，并且想要创建将返回该 index.html 的控制器。

【问题讨论】：

标签： spring-mvc spring-boot documentation spring-restdocs

【解决方案1】：

根据documentation，您可以配置您的构建系统（Maven、Gradle）以将 HTML 作为静态内容打包到 spring-boot jar 中，以便 Spring Boot“自动”提供服务

对于 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在本地验证

【讨论】：

我不明白如何访问静态上下文。 URL 应该像 localhost:8080/docs/index.html 吗？
@ИгорьКравченко，是这样的。请记住，您必须将“docs/index.html”添加到应用程序的所有 api 端点通用的基本路径。
使用spring boot在本地访问api指南，添加如下：

【解决方案2】：

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

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

【讨论】：

这不起作用。您是否有运行集成测试的万无一失或故障安全插件？可以分享完整的 POM 吗？

【解决方案3】：

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

中获取和托管文档

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

【讨论】：