Support return Object(In My dependencies)？

[qinkangdeid]

this tool is really awesome. I want to return an object in my RestFul API.the one Object is In my dependencies. like this:

1. I wrote an API:

   @GetMapping("/get")
   public ResponseEntity<Customer> get() {
       Customer customer = new Customer();
       customer.setAge(1);
       customer.setName("qinkangdeid");
       customer.setPhone("13522223333");
       return ResponseEntity.ok(customer);
   }

   2. the Customer Object in my External Libraries.

      
      public class Customer {

   /**

   • name */ private String name; /**
   • phone */ private String phone; /**
   • age */ private int age;

   public Customer() { }

   
   3. But inside the [`generated-snippets`]  the [auto-response-fields.adoc] Description is Empty

Path	Type	Optional	Description
name	String	true
phone	String	true
age	Integer	true

How should I display the description? Thanks.

[jmisur]

What you need to do is to include doclet maven/gradle configuration in your external library build, so that in creates json with field comments and packages it alongside classes inside that jar. From that point on, SARD will resolve the json because it will be on the classpath.

[Cepr0]

@jmisur Could you please explain how to include json with field comments of external library to a its jar properly so that SARD could used it in the main project?

I tried to add this to my lib pom.xml:

            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-javadoc-plugin</artifactId>
                <configuration>
                    <doclint>none</doclint>
                </configuration>
                <executions>
                    <execution>
                        <id>attach-javadocs</id>
                        <goals>
                            <goal>jar</goal>
                        </goals>
                    </execution>
                    <execution>
                        <id>attach-javadoc-json</id>
                        <goals>
                            <goal>jar</goal>
                        </goals>
                        <configuration>
                            <doclet>capital.scalable.restdocs.jsondoclet.ExtractDocumentationAsJsonDoclet</doclet>
                            <docletArtifact>
                                <groupId>capital.scalable</groupId>
                                <artifactId>spring-auto-restdocs-json-doclet</artifactId>
                                <version>2.0.1</version>
                            </docletArtifact>
                        </configuration>
                    </execution>
                </executions>
            </plugin>

This had added json files to the 'my-lib-javadoc.jar' but SARD hadn't used them (I suppose) because 'description' fields in the rendered html hadn't been filled.

Thanks in advance.

[jmisur]

I'm looking into doing this as part of our sample projects, which also share a lot of classes. I will let you know when it's ready.

[Cepr0]

@jmisur, Thank you. But could you please give me some direction now (maybe a link to the manual, etc.)?..

[qinkangdeid]

@jmisur Thank you. Waiting for your examples....

[jmisur]

Please take a look at this pom. The trick is to copy json files into target/classes directory (I couldn't make it work otherwise). https://github.com/ScaCap/spring-auto-restdocs/blob/1058450211cbef5b00a9681657a729343a7d26ff/samples/shared/pom.xml#L104..L125 PR #252

[Cepr0]

@jmisur it hasn't work for me ( I added your example to the pom of my exaternal lib 'my-lib':

            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-javadoc-plugin</artifactId>
                <configuration>
                    <doclint>none</doclint>
                </configuration>
                <executions>
                    <execution>
                        <id>attach-javadocs</id>
                        <goals>
                            <goal>jar</goal>
                        </goals>
                    </execution>

                    <execution>
                        <id>generate-javadoc-json</id>
                        <phase>process-sources</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>2.0.1</version>
                            </docletArtifact>
                            <reportOutputDirectory>${project.build.directory}</reportOutputDirectory>
                            <useStandardDocletOptions>false</useStandardDocletOptions>
                            <show>package</show>
                        </configuration>
                    </execution>
                </executions>
            </plugin>

            <plugin>
                <artifactId>maven-resources-plugin</artifactId>
                <version>3.1.0</version>
                <executions>
                    <execution>
                        <id>copy-resources</id>
                        <phase>prepare-package</phase>
                        <goals>
                            <goal>copy-resources</goal>
                        </goals>
                        <configuration>
                            <outputDirectory>${project.build.outputDirectory}</outputDirectory>
                            <resources>
                                <resource>
                                    <directory>${project.build.directory}/generated-javadoc-json</directory>
                                    <filtering>false</filtering>
                                </resource>
                            </resources>
                        </configuration>
                    </execution>
                </executions>
            </plugin>

I performed mvn install and then checked the 'my-lib.jar' contents - it had json files. But when I rebuilt my main project and checked the descriptions of the request/response fields of the classes from that lib - they were empty (

[Cepr0]

I found another workaround - in the main project I added the following to the configuration of maven-javadoc-plugin:

    <includeDependencySources>true</includeDependencySources>
    <dependencySourceIncludes>
        <dependencySourceInclude>my.project:*</dependencySourceInclude>
    </dependencySourceIncludes>

This allowed to include to my main project the javadocs from external lib package (my.project:*), but unfortunately, it downloaded javadocs from all(!) dependencies of my main project.

(See my related SO question)

[jmisur]

Delete generated html and try to do maven clean install on all your libs / sources. I didn't need to use this workaround you had to.

[qinkangdeid]

@jmisur Thank you very much! I successfully obtained the external jar package information using the latest snapshot version example.

[qinkangdeid]

@Cepr0 I successfully obtained the external jar package information using the latest snapshot version example.