properly generated javadoc jar in all modules (#81)

jmisur · web-flow · commit 2072a73ce2d8 · 2017-03-02T10:35:05.000+01:00
* properly generated javadoc jar in all modules

* build should run through all phases
diff --git a/.travis.yml b/.travis.yml
@@ -16,7 +16,7 @@ before_install:
   -DgroupId=org.springframework.restdocs -DartifactId=spring-restdocs-core -Dversion=1.1.2.RELEASE
   -Dpackaging=jar -Dclassifier=test
 script:
-- mvn test -B
+- mvn install -B -V
 - cd spring-auto-restdocs-example
 - ./gradlew check
 - cd ..
diff --git a/docs/index.html b/docs/index.html
@@ -602,24 +602,25 @@ <h3 id="gettingstarted-usage"><a class="link" href="#gettingstarted-usage">Usage
             &lt;extensions&gt;true&lt;/extensions&gt;
             &lt;executions&gt;
                 &lt;execution&gt;
+                    &lt;id&gt;generate-javadoc-json&lt;/id&gt;
                     &lt;phase&gt;compile&lt;/phase&gt;
                     &lt;goals&gt;
                         &lt;goal&gt;javadoc-no-fork&lt;/goal&gt;
                     &lt;/goals&gt;
+                    &lt;configuration&gt;
+                        &lt;doclet&gt;capital.scalable.restdocs.jsondoclet.ExtractDocumentationAsJsonDoclet&lt;/doclet&gt;
+                        &lt;docletArtifact&gt;
+                            &lt;groupId&gt;capital.scalable&lt;/groupId&gt;
+                            &lt;artifactId&gt;spring-auto-restdocs-json-doclet&lt;/artifactId&gt;
+                            &lt;version&gt;1.0.6&lt;/version&gt;
+                        &lt;/docletArtifact&gt;
+                        &lt;destDir&gt;generated-javadoc-json&lt;/destDir&gt;
+                        &lt;reportOutputDirectory&gt;${project.build.directory}&lt;/reportOutputDirectory&gt;
+                        &lt;useStandardDocletOptions&gt;false&lt;/useStandardDocletOptions&gt;
+                        &lt;show&gt;package&lt;/show&gt;
+                    &lt;/configuration&gt;
                 &lt;/execution&gt;
             &lt;/executions&gt;
-            &lt;configuration&gt;
-                &lt;doclet&gt;capital.scalable.restdocs.jsondoclet.ExtractDocumentationAsJsonDoclet&lt;/doclet&gt;
-                &lt;docletArtifact&gt;
-                    &lt;groupId&gt;capital.scalable&lt;/groupId&gt;
-                    &lt;artifactId&gt;spring-auto-restdocs-json-doclet&lt;/artifactId&gt;
-                    &lt;version&gt;1.0.6&lt;/version&gt;
-                &lt;/docletArtifact&gt;
-                &lt;destDir&gt;generated-javadoc-json&lt;/destDir&gt;
-                &lt;reportOutputDirectory&gt;${project.build.directory}&lt;/reportOutputDirectory&gt;
-                &lt;useStandardDocletOptions&gt;false&lt;/useStandardDocletOptions&gt;
-                &lt;show&gt;package&lt;/show&gt;
-            &lt;/configuration&gt;
         &lt;/plugin&gt;
         ...
     &lt;/plugins&gt;
@@ -1498,7 +1499,7 @@ <h4 id="contributing-building-build"><a class="link" href="#contributing-buildin
 </div>
 <div id="footer">
 <div id="footer-text">
-    Last updated 2017-03-01 19:17:18 CET
+    Last updated 2017-03-02 09:48:15 CET
 </div>
 </div>
 <link rel="stylesheet" href="highlight/styles/github.min.css">
diff --git a/spring-auto-restdocs-core/pom.xml b/spring-auto-restdocs-core/pom.xml
@@ -123,24 +123,25 @@
                 <extensions>true</extensions>
                 <executions>
                     <execution>
+                        <id>generate-javadoc-json</id>
                         <phase>compile</phase>
                         <goals>
                             <goal>test-javadoc-no-fork</goal>
                         </goals>
+                        <configuration>
+                            <doclet>capital.scalable.restdocs.jsondoclet.ExtractDocumentationAsJsonDoclet</doclet>
+                            <docletArtifact>
+                                <groupId>capital.scalable</groupId>
+                                <artifactId>spring-auto-restdocs-json-doclet</artifactId>
+                                <version>${project.parent.version}</version>
+                            </docletArtifact>
+                            <destDir>generated-javadoc-json</destDir>
+                            <reportOutputDirectory>${project.build.directory}</reportOutputDirectory>
+                            <useStandardDocletOptions>false</useStandardDocletOptions>
+                            <show>package</show>
+                        </configuration>
                     </execution>
                 </executions>
-                <configuration>
-                    <doclet>capital.scalable.restdocs.jsondoclet.ExtractDocumentationAsJsonDoclet</doclet>
-                    <docletArtifact>
-                        <groupId>capital.scalable</groupId>
-                        <artifactId>spring-auto-restdocs-json-doclet</artifactId>
-                        <version>${project.parent.version}</version>
-                    </docletArtifact>
-                    <destDir>generated-javadoc-json</destDir>
-                    <reportOutputDirectory>${project.build.directory}</reportOutputDirectory>
-                    <useStandardDocletOptions>false</useStandardDocletOptions>
-                    <show>package</show>
-                </configuration>
             </plugin>
         </plugins>
     </build>
diff --git a/spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/response/ResponseModifyingPreprocessors.java b/spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/response/ResponseModifyingPreprocessors.java
@@ -28,6 +28,9 @@ public class ResponseModifyingPreprocessors {
      * Only modifies the content of a response.
      * <p>
      * Contains {@link #replaceBinaryContent()}, {@link #limitJsonArrayLength(ObjectMapper)}
+     *
+     * @param objectMapper object mapper instance
+     * @return a response shortening preprocessor
      */
     public static OperationResponsePreprocessor shortenContent(ObjectMapper objectMapper) {
         return Preprocessors.preprocessResponse(replaceBinaryContent(),
@@ -36,13 +39,18 @@ public static OperationResponsePreprocessor shortenContent(ObjectMapper objectMa
 
     /**
      * For binary content, replaces value with "&lt;binary&gt;".
+     *
+     * @return a preprocessor replacing binary content
      */
     public static OperationPreprocessor replaceBinaryContent() {
         return new ContentModifyingOperationPreprocessor(new BinaryReplacementContentModifier());
     }
 
     /**
      * For JSON content, cuts the length of all JSON arrays in the response to 3 elements.
+     *
+     * @param objectMapper object mapper to use
+     * @return an array limiting preprocessor
      */
     public static OperationPreprocessor limitJsonArrayLength(ObjectMapper objectMapper) {
         return new ContentModifyingOperationPreprocessor(
diff --git a/spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/section/SectionBuilder.java b/spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/section/SectionBuilder.java
@@ -22,6 +22,9 @@
 
 import capital.scalable.restdocs.SnippetRegistry;
 
+/**
+ * Builder for configuring a section snippet.
+ */
 public class SectionBuilder {
 
     public static final Collection<String> DEFAULT_SNIPPETS = Arrays.asList(
@@ -45,6 +48,7 @@ public SectionBuilder() {
      *
      * @param snippetNames snippet names to use; if not specified, {@link #DEFAULT_SNIPPETS} will
      *                     be used
+     * @return this
      */
     public SectionBuilder snippetNames(List<String> snippetNames) {
         this.snippetNames = snippetNames;
@@ -56,9 +60,10 @@ public SectionBuilder snippetNames(List<String> snippetNames) {
      *
      * @param snippetNames snippet names to use; if not specified, {@link #DEFAULT_SNIPPETS} will
      *                     be used
+     * @return this
      */
-    public SectionBuilder snippetNames(String... sectionNames) {
-        this.snippetNames = Arrays.asList(sectionNames);
+    public SectionBuilder snippetNames(String... snippetNames) {
+        this.snippetNames = Arrays.asList(snippetNames);
         return this;
     }
 
@@ -68,6 +73,7 @@ public SectionBuilder snippetNames(String... sectionNames) {
      *
      * @param skipEmpty true if snippets with no content should not be included in the section;
      *                  false otherwise (default)
+     * @return this
      */
     public SectionBuilder skipEmpty(boolean skipEmpty) {
         this.skipEmpty = skipEmpty;
diff --git a/spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/section/SectionSupport.java b/spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/section/SectionSupport.java
@@ -21,16 +21,23 @@
 public interface SectionSupport {
     /**
      * File name (= section name).
+     *
+     * @return file name
      */
     String getFileName();
 
     /**
      * Section header.
+     *
+     * @return header
      */
     String getHeader();
 
     /**
      * Flag if section will render non-empty content.
+     *
+     * @param operation operation
+     * @return true if snippet will return non-empty content; false otherwise
      */
     boolean hasContent(Operation operation);
 }
diff --git a/spring-auto-restdocs-docs/getting-started.adoc b/spring-auto-restdocs-docs/getting-started.adoc
@@ -50,24 +50,25 @@ Spring Auto REST Docs has the following minimum requirements:
             <extensions>true</extensions>
             <executions>
                 <execution>
+                    <id>generate-javadoc-json</id>
                     <phase>compile</phase>
                     <goals>
                         <goal>javadoc-no-fork</goal>
                     </goals>
+                    <configuration>
+                        <doclet>capital.scalable.restdocs.jsondoclet.ExtractDocumentationAsJsonDoclet</doclet>
+                        <docletArtifact>
+                            <groupId>capital.scalable</groupId>
+                            <artifactId>spring-auto-restdocs-json-doclet</artifactId>
+                            <version>${latestRelease}</version>
+                        </docletArtifact>
+                        <destDir>generated-javadoc-json</destDir>
+                        <reportOutputDirectory>\${project.build.directory}</reportOutputDirectory>
+                        <useStandardDocletOptions>false</useStandardDocletOptions>
+                        <show>package</show>
+                    </configuration>
                 </execution>
             </executions>
-            <configuration>
-                <doclet>capital.scalable.restdocs.jsondoclet.ExtractDocumentationAsJsonDoclet</doclet>
-                <docletArtifact>
-                    <groupId>capital.scalable</groupId>
-                    <artifactId>spring-auto-restdocs-json-doclet</artifactId>
-                    <version>${latestRelease}</version>
-                </docletArtifact>
-                <destDir>generated-javadoc-json</destDir>
-                <reportOutputDirectory>\${project.build.directory}</reportOutputDirectory>
-                <useStandardDocletOptions>false</useStandardDocletOptions>
-                <show>package</show>
-            </configuration>
         </plugin>
         ...
     </plugins>
diff --git a/spring-auto-restdocs-example/generated-docs/index.html b/spring-auto-restdocs-example/generated-docs/index.html
@@ -1036,7 +1036,7 @@ <h4 id="_response_fields_3"><a class="anchor" href="#_response_fields_3"></a>2.3
       <h4 id="_example_request"><a class="anchor" href="#_example_request"></a>2.3.6. Example request</h4>
       <div class="listingblock">
         <div class="content">
-          <pre class="highlightjs highlight"><code class="language-bash" data-lang="bash">$ curl 'http://localhost:8080/items' -i -X POST -H 'Content-Type: application/json' -H 'Authorization: Bearer cea8f330-458f-4c41-a94d-35b5513bd588' -d '{"description":"Hot News"}'</code></pre>
+          <pre class="highlightjs highlight"><code class="language-bash" data-lang="bash">$ curl 'http://localhost:8080/items' -i -X POST -H 'Content-Type: application/json' -H 'Authorization: Bearer cd682a43-bb11-459e-b986-4b1cf15c4e5b' -d '{"description":"Hot News"}'</code></pre>
         </div>
       </div>
     </div>
@@ -1247,7 +1247,7 @@ <h4 id="_response_fields_4"><a class="anchor" href="#_response_fields_4"></a>2.4
       <h4 id="_example_request_2"><a class="anchor" href="#_example_request_2"></a>2.4.6. Example request</h4>
       <div class="listingblock">
         <div class="content">
-          <pre class="highlightjs highlight"><code class="language-bash" data-lang="bash">$ curl 'http://localhost:8080/items/1' -i -X PUT -H 'Content-Type: application/json' -H 'Authorization: Bearer cea8f330-458f-4c41-a94d-35b5513bd588' -d '{"description":"Hot News"}'</code></pre>
+          <pre class="highlightjs highlight"><code class="language-bash" data-lang="bash">$ curl 'http://localhost:8080/items/1' -i -X PUT -H 'Content-Type: application/json' -H 'Authorization: Bearer cd682a43-bb11-459e-b986-4b1cf15c4e5b' -d '{"description":"Hot News"}'</code></pre>
         </div>
       </div>
     </div>
@@ -1314,7 +1314,8 @@ <h4 id="_path_parameters_4"><a class="anchor" href="#_path_parameters_4"></a>2.5
           <td class="tableblock halign-left valign-top"><p class="tableblock">id</p></td>
           <td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td>
           <td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
-          <td class="tableblock halign-left valign-top"><p class="tableblock">Must be a valid ID.</p></td>
+          <td class="tableblock halign-left valign-top"><p class="tableblock">item ID.<br>
+            Must be a valid ID.</p></td>
         </tr>
         </tbody>
       </table>
@@ -1341,7 +1342,7 @@ <h4 id="_response_fields_5"><a class="anchor" href="#_response_fields_5"></a>2.5
       <h4 id="_example_request_3"><a class="anchor" href="#_example_request_3"></a>2.5.6. Example request</h4>
       <div class="listingblock">
         <div class="content">
-          <pre class="highlightjs highlight"><code class="language-bash" data-lang="bash">$ curl 'http://localhost:8080/items/1' -i -X DELETE -H 'Authorization: Bearer cea8f330-458f-4c41-a94d-35b5513bd588'</code></pre>
+          <pre class="highlightjs highlight"><code class="language-bash" data-lang="bash">$ curl 'http://localhost:8080/items/1' -i -X DELETE -H 'Authorization: Bearer cd682a43-bb11-459e-b986-4b1cf15c4e5b'</code></pre>
         </div>
       </div>
     </div>
@@ -1762,8 +1763,8 @@ <h4 id="_example_response_5"><a class="anchor" href="#_example_response_5"></a>2
   } ],
   "pageable" : null,
   "total" : 1,
-  "last" : true,
   "totalPages" : 1,
+  "last" : true,
   "totalElements" : 1,
   "size" : 0,
   "number" : 0,
diff --git a/spring-auto-restdocs-example/pom.xml b/spring-auto-restdocs-example/pom.xml
@@ -13,7 +13,7 @@
 
     <groupId>capital.scalable</groupId>
     <artifactId>spring-auto-restdocs-example</artifactId>
-    <version>1.0.6</version> <!-- not related to actual project version -->
+    <version>1.0.6</version> <!-- not related to spring-auto-restdocs version -->
 
     <name>Spring Auto REST Docs Example Project</name>
     <description>Example project for Spring Auto REST Docs</description>
@@ -158,33 +158,79 @@
                     </execution>
                 </executions>
             </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-source-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>attach-sources</id>
+                        <goals>
+                            <goal>jar-no-fork</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
             <plugin>
                 <artifactId>maven-javadoc-plugin</artifactId>
                 <extensions>true</extensions>
                 <executions>
                     <execution>
+                        <id>attach-javadocs</id>
+                        <goals>
+                            <goal>jar</goal>
+                        </goals>
+                    </execution>
+                    <execution>
+                        <id>generate-javadoc-json</id>
                         <phase>compile</phase>
                         <goals>
                             <goal>javadoc-no-fork</goal>
                         </goals>
+                        <configuration>
+                            <doclet>capital.scalable.restdocs.jsondoclet.ExtractDocumentationAsJsonDoclet</doclet>
+                            <docletArtifact>
+                                <groupId>capital.scalable</groupId>
+                                <artifactId>spring-auto-restdocs-json-doclet</artifactId>
+                                <version>${spring-auto-restdocs.version}</version>
+                            </docletArtifact>
+                            <destDir>generated-javadoc-json</destDir>
+                            <reportOutputDirectory>${project.build.directory}</reportOutputDirectory>
+                            <useStandardDocletOptions>false</useStandardDocletOptions>
+                            <show>package</show>
+                        </configuration>
                     </execution>
                 </executions>
-                <configuration>
-                    <doclet>capital.scalable.restdocs.jsondoclet.ExtractDocumentationAsJsonDoclet</doclet>
-                    <docletArtifact>
-                        <groupId>capital.scalable</groupId>
-                        <artifactId>spring-auto-restdocs-json-doclet</artifactId>
-                        <version>${spring-auto-restdocs.version}</version>
-                    </docletArtifact>
-                    <destDir>generated-javadoc-json</destDir>
-                    <reportOutputDirectory>${project.build.directory}</reportOutputDirectory>
-                    <useStandardDocletOptions>false</useStandardDocletOptions>
-                    <show>package</show>
-                </configuration>
             </plugin>
         </plugins>
     </build>
 
+    <profiles>
+        <profile>
+            <id>sign-artifacts</id>
+            <activation>
+                <property>
+                    <name>gpg.passphrase</name>
+                </property>
+            </activation>
+            <build>
+                <plugins>
+                    <plugin>
+                        <artifactId>maven-gpg-plugin</artifactId>
+                        <executions>
+                            <execution>
+                                <id>sign-artifacts</id>
+                                <phase>verify</phase>
+                                <goals>
+                                    <goal>sign</goal>
+                                </goals>
+                            </execution>
+                        </executions>
+                    </plugin>
+                </plugins>
+            </build>
+        </profile>
+    </profiles>
+
     <distributionManagement>
         <snapshotRepository>
             <id>ossrh</id>
diff --git a/spring-auto-restdocs-example/src/main/java/capital/scalable/restdocs/example/items/ItemResource.java b/spring-auto-restdocs-example/src/main/java/capital/scalable/restdocs/example/items/ItemResource.java
