Spring REST Docs генерирует пустой индексный файл
Я новичок в Spring REST Docs и использую последнюю версию 1.2.1. У меня есть рабочие контроллеры RESTful, и у меня есть куча рабочих тестов. Теперь я представляю аспект документации, чтобы документально оформить их для новых разработчиков.
У меня pom.xml настроен так:
<dependency>
<groupId>org.springframework.restdocs</groupId>
<artifactId>spring-restdocs-mockmvc</artifactId>
<version>1.2.1.RELEASE</version>
<scope>test</scope>
</dependency>
и вот где находятся плагины сборки:
<properties>
<snippetsDirectory>${project.build.directory}/generated-snippets</snippetsDirectory>
</properties>
<build>
<outputDirectory>target/${project.artifactId}-${project.version}/WEB-INF/classes</outputDirectory>
<plugins>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>buildnumber-maven-plugin</artifactId>
<version>1.4</version>
<executions>
<execution>
<phase>validate</phase>
<goals>
<goal>create</goal>
</goals>
</execution>
</executions>
<configuration>
<doCheck>false</doCheck>
<doUpdate>false</doUpdate>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<source>1.8</source>
<target>1.8</target>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-war-plugin</artifactId>
<version>3.1.0</version>
<configuration>
<archive>
<manifest>
<addDefaultImplementationEntries>true</addDefaultImplementationEntries>
</manifest>
<manifestEntries>
<Git-Revision>${buildNumber}</Git-Revision>
</manifestEntries>
</archive>
<archiveClasses>true</archiveClasses>
<webResources>
<!-- in order to interpolate version from pom into appengine-web.xml -->
<resource>
<directory>${basedir}/src/main/webapp/WEB-INF</directory>
<filtering>true</filtering>
<targetPath>WEB-INF</targetPath>
</resource>
</webResources>
<failOnMissingWebXml>false</failOnMissingWebXml>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.20</version>
<configuration>
<includes>
<include>**/*Documentation.java</include>
</includes>
</configuration>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.5</version>
<executions>
<execution>
<id>generate-docs</id>
<phase>prepare-package</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>html</backend>
<doctype>book</doctype>
<sourceDocumentName>index.adoc</sourceDocumentName>
<attributes>
<snippets>${snippetsDirectory}</snippets>
</attributes>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<artifactId>maven-resources-plugin</artifactId>
<version>3.0.2</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>
</plugins>
</build>
И у меня есть тесты, которые работают, и в /target я видел некоторые каталоги, созданные с несколькими файлами *.adoc. Что здорово.
У меня есть /src/main/asciidoc/index.adoc созданный, и когда я делаю свою сборку, она успешна. В файле index.adoc ничего нет, должно быть? Итак, после успешной сборки, я получаю множество "adoc" файлов в:
/ MyApp-платформы WS / цель / сгенерированные-фрагменты
Я также получаю файл "index.html" в папке: /myapp-platform-ws/target/generate-docs Но в нем ничего нет....
У меня есть несколько других контроллеров, каждый с несколькими методами, которые я буду документировать. Это все хорошо. Тем не менее, я хотел бы найти некоторый метод, где я могу иметь несколько html-файлов для различных файлов adoc.
Spring REST Docs для меня действительно новый, и я просто пробую много нового, чтобы опубликовать его в своей команде.
Любая помощь приветствуется! Спасибо!
=============== ОБНОВЛЕНИЕ 1.0 =================
Итак, я добавил этот плагин перед плагином "asciidoctor".
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.20</version>
<configuration>
<includes>
<include>**/*Documentation.java</include>
</includes>
</configuration>
</plugin>
И да, мне пришлось включить версию, потому что в противном случае я бы получил сообщение об ошибке, сказав, что ее там нет, но сборка все еще была успешной. Однако сейчас ни один из моих тестов не будет запущен.
Я также изменил свой index.adoc, добавив в него следующее:
[[overview-headers]]
== Headers
Every response has the following header(s):
<h>Organizations</h>
include::{snippets}/orgs/response-headers.adoc[]
include::{snippets}/orgs/portal/response-headers.adoc[]
И так, поскольку тесты не выполняются, он не добавляет эти файлы. Я также подозреваю, что response-headers.adoc также не генерируется. Когда тесты были запущены, я получал фрагменты.
Я думаю, что буду на правильном пути, если смогу снова запустить тесты. Я не пропускаю тесты вообще.
=============== ОБНОВЛЕНИЕ 2.0 =================
Я изменил плагин surefire, чтобы фактически работать с тестами, которые у меня есть:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.20</version>
<configuration>
<includes>
<include>**/*Test.java</include>
</includes>
</configuration>
</plugin>
Поскольку все мои тесты заканчиваются на /*Test.java
Таким образом, все мои тесты были выполнены.
Поскольку я получал сообщение об отсутствии файлов *.adoc, я дважды проверил
<properties>
<snippetsDirectory>${project.build.directory}/generated-snippets</snippetsDirectory>
</properties>
была настроена правильно, но я не знал, что это было удалено, поэтому я добавил его снова, и я перестал получать сообщения об ошибках.
Я не помню, упоминал ли я об этом, но я добавил детали в index.adoc, и тогда я наконец смог получить сгенерированный index.html с содержимым в нем.
Теперь мне просто нужно больше узнать AsciiDoctor, и я могу обновить index.adoc для всех POSTS и PUT, а также GET.
1 ответ
После экспериментирования, как описано выше, я наконец получил это к работе. Мне просто нужно было правильно настроить конфигурацию, и, наконец, она работает. Теперь у меня есть файлы index.adoc и файл index.html, созданные с контентом.
Теперь мне просто нужно больше узнать AsciiDoctor, и я могу обновить index.adoc для всех POSTS и PUT, а также GET.