RestdocsNotExpanded in a separate module (#303)

Closes #282

Author: jmisur

pom.xml

@@ -187,6 +187,7 @@
             <modules>
                 <module>spring-auto-restdocs-json-doclet</module>
                 <module>spring-auto-restdocs-dokka-json</module>
+                <module>spring-auto-restdocs-annotations</module>
                 <module>spring-auto-restdocs-core</module>
                 <module>spring-auto-restdocs-docs</module>
             </modules>
@@ -204,6 +205,7 @@
             </properties>
             <modules>
                 <module>spring-auto-restdocs-json-doclet-jdk9</module>
+                <module>spring-auto-restdocs-annotations</module>
                 <module>spring-auto-restdocs-core</module>
                 <module>spring-auto-restdocs-docs</module>
             </modules>

samples/java-webmvc/pom.xml

@@ -85,6 +85,7 @@
             <groupId>capital.scalable</groupId>
             <artifactId>spring-auto-restdocs-core</artifactId>
             <version>${spring-auto-restdocs.version}</version>
+            <scope>test</scope>
         </dependency>
         <dependency>
             <groupId>org.springframework.data</groupId>

samples/java-webmvc/src/main/java/capital/scalable/restdocs/example/items/ItemResource.java

@@ -7,9 +7,9 @@
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
- * 
+ *
  *      http://www.apache.org/licenses/LICENSE-2.0
- * 
+ *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -37,7 +37,6 @@
 import capital.scalable.restdocs.example.constraints.English;
 import capital.scalable.restdocs.example.constraints.German;
 import capital.scalable.restdocs.example.constraints.Id;
-import org.apache.commons.lang3.BooleanUtils;
 import org.springframework.data.domain.Page;
 import org.springframework.data.domain.PageImpl;
 import org.springframework.data.domain.Pageable;
@@ -280,7 +279,7 @@ public HypermediaItemResponse getHypermediaItem(@PathVariable("id") @Id String i
         response.add(linkTo(methodOn(ItemResource.class).getHypermediaItem(id, embedded)).withSelfRel());
         response.add(linkTo(methodOn(ItemResource.class).getItem(id)).withRel("classicItem"));
         response.add(linkTo(methodOn(ItemResource.class).processSingleItem(id, null)).withRel("process"));
-        if (BooleanUtils.isTrue(embedded)) {
+        if (embedded != null && embedded) {
             response.embed("children", new Object[]{CHILD});
             response.embed("attributes", ATTRIBUTES);
             response.embed("meta", META);

samples/shared/pom.xml

@@ -46,6 +46,11 @@
             <groupId>javax.validation</groupId>
             <artifactId>validation-api</artifactId>
         </dependency>
+        <dependency>
+            <groupId>capital.scalable</groupId>
+            <artifactId>spring-auto-restdocs-annotations</artifactId>
+            <version>${spring-auto-restdocs.version}</version>
+        </dependency>
     </dependencies>
 
     <profiles>

samples/shared/src/main/java/capital/scalable/restdocs/example/items/Metadata2.java

@@ -20,12 +20,20 @@
 
 package capital.scalable.restdocs.example.items;
 
+import capital.scalable.restdocs.jackson.RestdocsNotExpanded;
+
 public class Metadata2 extends Metadata {
     /**
      * Order attribute. Available only if metadata type=2
      */
     private Integer order;
 
+    /**
+     * Sub metadata (recursive). Not expanded as client should not see it.
+     */
+    @RestdocsNotExpanded
+    private Metadata2 sub;
+
     Metadata2() {
     }
 

spring-auto-restdocs-annotations/pom.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>capital.scalable</groupId>
+        <artifactId>spring-auto-restdocs-parent</artifactId>
+        <version>2.0.5-SNAPSHOT</version>
+        <relativePath>..</relativePath>
+    </parent>
+
+    <artifactId>spring-auto-restdocs-annotations</artifactId>
+    <packaging>jar</packaging>
+
+    <name>Spring Auto REST Docs Annotations</name>
+    <description>Spring Auto REST Docs supporting annotations</description>
+
+</project>

…estdocs/jackson/RestdocsNotExpanded.java …estdocs/jackson/RestdocsNotExpanded.javaspring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/jackson/RestdocsNotExpanded.java renamed to spring-auto-restdocs-annotations/src/main/java/capital/scalable/restdocs/jackson/RestdocsNotExpanded.java spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/jackson/RestdocsNotExpanded.java renamed to spring-auto-restdocs-annotations/src/main/java/capital/scalable/restdocs/jackson/RestdocsNotExpanded.java

@@ -22,6 +22,11 @@
     </properties>
 
     <dependencies>
+        <dependency>
+            <groupId>capital.scalable</groupId>
+            <artifactId>spring-auto-restdocs-annotations</artifactId>
+            <version>${project.version}</version>
+        </dependency>
         <dependency>
             <groupId>org.springframework.restdocs</groupId>
             <artifactId>spring-restdocs-core</artifactId>

spring-auto-restdocs-core/pom.xml

@@ -29,7 +29,7 @@ For Java 9 support, use `spring-auto-restdocs-json-doclet-jdk9` as doclet depend
     <groupId>capital.scalable</groupId>
     <artifactId>spring-auto-restdocs-core</artifactId>
     <version>${latestRelease}</version>
-    <scope>test</scope> <1>
+    <scope>test</scope>
 </dependency>
 
 <build>
@@ -42,10 +42,10 @@ For Java 9 support, use `spring-auto-restdocs-json-doclet-jdk9` as doclet depend
                 </includes>
                 <systemPropertyVariables>
                     <org.springframework.restdocs.outputDir>
-                        \${project.build.directory}/generated-snippets <2>
+                        \${project.build.directory}/generated-snippets <1>
                     </org.springframework.restdocs.outputDir>
                     <org.springframework.restdocs.javadocJsonDir>
-                        \${project.build.directory}/generated-javadoc-json <3>
+                        \${project.build.directory}/generated-javadoc-json <2>
                     </org.springframework.restdocs.javadocJsonDir>
                 </systemPropertyVariables>
              </configuration>
@@ -64,11 +64,11 @@ For Java 9 support, use `spring-auto-restdocs-json-doclet-jdk9` as doclet depend
                         <doclet>capital.scalable.restdocs.jsondoclet.ExtractDocumentationAsJsonDoclet</doclet>
                         <docletArtifact>
                             <groupId>capital.scalable</groupId>
-                            <artifactId>spring-auto-restdocs-json-doclet</artifactId> <4>
+                            <artifactId>spring-auto-restdocs-json-doclet</artifactId> <3>
                             <version>${latestRelease}</version>
                         </docletArtifact>
-                        <destDir>generated-javadoc-json</destDir> <3>
-                        <reportOutputDirectory>\${project.build.directory}</reportOutputDirectory> <3>
+                        <destDir>generated-javadoc-json</destDir> <2>
+                        <reportOutputDirectory>\${project.build.directory}</reportOutputDirectory> <2>
                         <useStandardDocletOptions>false</useStandardDocletOptions>
                         <show>package</show>
                     </configuration>
@@ -79,12 +79,11 @@ For Java 9 support, use `spring-auto-restdocs-json-doclet-jdk9` as doclet depend
     </plugins>
 </build>
 ----
-<1> Has to be removed if `@RestdocsNotExpanded` is used.
-<2> (Optional) Determines directory where snippets are saved. Defaults to `generated-snippets` in build directory.
-<3> (Optional) Determines where JSON files are saved. Defaults to `generated-javadoc-json` in build directory.
+<1> (Optional) Determines directory where snippets are saved. Defaults to `generated-snippets` in build directory.
+<2> (Optional) Determines where JSON files are saved. Defaults to `generated-javadoc-json` in build directory.
 Multiple directories can be listed by separating them with `,`.
 The directories are processed in order and only the first found JSON file is used.
-<4> For Java 9 support, use `spring-auto-restdocs-json-doclet-jdk9` as doclet dependency.
+<3> For Java 9 support, use `spring-auto-restdocs-json-doclet-jdk9` as doclet dependency.
 
 +
 [source,javascript]
@@ -95,26 +94,26 @@ configurations {
 }
 
 ext {
-    javadocJsonDir = file("$buildDir/generated-javadoc-json") <3>
+    javadocJsonDir = file("$buildDir/generated-javadoc-json") <2>
 }
 
 dependencies {
-    testCompile group: 'capital.scalable', name: 'spring-auto-restdocs-core', version: '${latestRelease}' <1>
-    jsondoclet group: 'capital.scalable', name: 'spring-auto-restdocs-json-doclet', version: '${latestRelease}' <4>
+    testCompile group: 'capital.scalable', name: 'spring-auto-restdocs-core', version: '${latestRelease}'
+    jsondoclet group: 'capital.scalable', name: 'spring-auto-restdocs-json-doclet', version: '${latestRelease}' <3>
 }
 
 task jsonDoclet(type: Javadoc, dependsOn: compileJava) {
     source = sourceSets.main.allJava
     classpath = sourceSets.main.compileClasspath
-    destinationDir = javadocJsonDir <3>
+    destinationDir = javadocJsonDir <2>
     options.docletpath = configurations.jsondoclet.files.asType(List)
     options.doclet = 'capital.scalable.restdocs.jsondoclet.ExtractDocumentationAsJsonDoclet'
     options.memberLevel = JavadocMemberLevel.PACKAGE
 }
 
 test {
-    systemProperty 'org.springframework.restdocs.outputDir', snippetsDir <2>
-    systemProperty 'org.springframework.restdocs.javadocJsonDir', javadocJsonDir <3>
+    systemProperty 'org.springframework.restdocs.outputDir', snippetsDir <1>
+    systemProperty 'org.springframework.restdocs.javadocJsonDir', javadocJsonDir <2>
 
     dependsOn jsonDoclet
 }
@@ -123,13 +122,12 @@ jar {
     dependsOn asciidoctor
 }
 ----
-<1> Has to be `compile` instead of `testCompile` if `@RestdocsNotExpanded` is used.
-<2> (Optional) Determines directory where snippets are saved. Defaults to `generated-snippets` in build directory.
-<3> (Optional) Determines where JSON files are saved.
+<1> (Optional) Determines directory where snippets are saved. Defaults to `generated-snippets` in build directory.
+<2> (Optional) Determines where JSON files are saved.
 Defaults to `generated-javadoc-json` in build directory.
 Multiple directories can be listed by separating them with `,`.
 The directories are processed in order and only the first found JSON file is used.
-<4> For Java 9 support, use `spring-auto-restdocs-json-doclet-jdk9` as doclet dependency.
+<3> For Java 9 support, use `spring-auto-restdocs-json-doclet-jdk9` as doclet dependency.
 
 . Configure MockMvc or WebTestClient
 +

spring-auto-restdocs-docs/getting-started.adoc

@@ -51,4 +51,9 @@ See how it looks in the link:{html-preview}{example-dir}/generated-docs/index.ht
 For custom translations of section titles, table headers and other messages:
 
 1. Create a file `SnippetMessages.properties` in `capital.scalable.restdocs.i18n` package.
-2. Add translations to the file using keys from link:{master-dir}/spring-auto-restdocs-core/src/test/resources/capital/scalable/restdocs/i18n/DefaultSnippetMessages.properties[DefaultSnippetMessages].
+2. Add translations to the file using keys from link:{master-dir}/spring-auto-restdocs-core/src/test/resources/capital/scalable/restdocs/i18n/DefaultSnippetMessages.properties[DefaultSnippetMessages].[[localization]]
+
+=== Recursive structures support
+
+To prevent infinite loop in recursive structures, annotate the recursive field with the `@RestdocsNotExpanded` annotation
+from the `spring-auto-restdocs-annotations` maven module.