与应用程序一起发布spring-restdocs html文档

Question

我有带有spring的spring-boot应用程序，我希望在该应用程序中为生成的文档创建端点。使用生成的html文档(由asciidoctor)公开端点的最佳方法是什么？

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

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

例如，我在‘build/asctiidoctor/html5 5’文件夹中有index.html，并希望创建将返回该index.html的控制器。

Answer 1

根据文档，您可以将您的构建系统(Maven，Gradle)配置为将HTML打包到Spring中作为静态内容，这样Spring‘自动’就可以为其提供服务。

在第4.6级和Spring 2.0的情况下，：

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

然后可以通过'localhost:<your-port>/<your-context-path/docs/index.html在本地进行验证。

Answer 2

若要使用url http://localhost:8081/docs/api-guide.html在本地使用spring引导访问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>`

Answer 3

在从AsciiDoc中生成html之后，只需将html文件复制到target/generated-docs (参见https://spring.io/guides/gs/testing-restdocs/)。然后，Spring将在端点<.>/docs/index.html中获取并保存文档。

你可以用maven-resources-plugin做这份工作。