服務Spring Rest文檔

Question

我具有以下Spring Rest Docs maven配置，當我打包Spring Boot應用程序時，這會使我生成的文檔最終出現在WEB-INF/classes/static/docs 。

 <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.3</version>
                <executions>
                    <execution>
                        <id>generate-docs</id>
                        <phase>prepare-package</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>2.7</version>
                <executions>
                    <execution>
                        <id>copy-resources</id>
                        <phase>prepare-package</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>

然后我試圖在此控制器中提供它們（ my-api-doc.html是生成的文檔的名稱）

@Controller
public class DocsController {

    @RequestMapping("/docs")
    private String docs() {
        return "my-api-doc";
    }

}

但是我得到了404。如何使我的Spring Boot應用程序提供WEB-INF/classes/static/docs的WAR文件中的html？

Answer 1

根據Spring Boot docs的介紹 ，靜態內容應位於四個預定義位置之一。 /WEB-INF/classes/static不是其中之一。 嘗試將生成的文檔移動到/public或/META-INF/resources 。

Answer 2

我的錯誤是試圖從控制器提供html。 最終位於WEB-INF/classes/static中的文件應被直接訪問，並且在控制器尋找視圖時不會被解析。 我可以使用my-api/docs/my-api-doc.html直接訪問文件

Answer 3

嘗試使用Swagger（位於https://swagger.io/ ）獲取文檔。 實際上，您可以托管API的文檔，並在每次更新API時自動獲得更新（這減輕了對API進行更新時更新文檔的負擔）。
另外，靜態文件夾用於將View附加到Spring API，我建議不要在其中保存任何文件。