Я новичок в Spring REST Docs и использую последнюю версию 1.2.1.Release. У меня есть работающие контроллеры 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-platform-ws/target/generated-snippets.
Я также получаю файл "index.html" в папке: /myapp-platform-ws/target/generated-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.
