Публикация html-документации spring-restdocs с приложением

У меня есть приложение spring-boot с spring-restdocs, и я хочу создать конечную точку в этом приложении для сгенерированной документации. Каков наилучший подход для предоставления конечной точки сгенерированной html-документацией (от asciidoctor)?

Я могу включить index.html в jar-файл, но на самом деле не знаю, как создать конечную точку, которая будет использовать этот html и выставлять наружу. Этот html создается после этапа тестирования и до этапа сборки jar.

Из официальной документации: вы можете опубликовать созданную HTML-документацию на статическом веб-сайте или упаковать ее и использовать из самого приложения.

например У меня есть index.html в папке build/asctiidoctor/html5, и я хочу создать контроллер, который будет возвращать этот index.html.


spring-boot spring-mvc documentation spring-restdocs
person Игорь Кравченко    schedule 29.03.2018    source источник

Ответы (3)


arrow_upward
10
arrow_downward

Согласно документации вы можете настроить свою систему сборки (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

person Mykola Slutskyi    schedule 29.03.2018
comment
Я не понимаю, как получить доступ к статическому контексту. Должен ли URL-адрес выглядеть как localhost:8080/docs/index.html? - person Игорь Кравченко; 30.03.2018
comment
@ИгорьКравченко, да как-то так. Имейте в виду, что вы должны добавить «docs/index.html» к базовому пути, который является общим для всех конечных точек API вашего приложения. - person Mykola Slutskyi; 30.03.2018
comment
чтобы получить локальный доступ к руководству по API с помощью весенней загрузки, добавьте следующее: - person Java_Explorer; 03.11.2020

arrow_upward
1
arrow_downward

Чтобы получить локальный доступ к руководству по 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>`
person Java_Explorer    schedule 03.11.2020
comment
Это не работает. Есть ли у вас надежные или отказоустойчивые плагины для запуска интеграционных тестов? Можете ли вы поделиться полным POM? - person Shehan Simen; 23.02.2021

arrow_upward
0
arrow_downward

После создания html из AsciiDoc просто скопируйте html файлы в target/generated-docs (см. https://spring.io/guides/gs/testing-restdocs/). Затем Spring-Boot возьмет и разместит документацию в конечной точке ‹...>/docs/index.html.

Вы можете использовать maven-resources-plugin для этой работы.

person hilbert    schedule 22.10.2019