introduce

In general, we use Springfox to generate Swagger API documents, but Springfox does not support generation from Javadoc and can only annotate documents.

Thus, when sharing some POJO classes, you need to write two copies to generate both the Javadoc document and the Swagger document.

In addition, when using the Swagger annotation, it is generally used as follows:

@ApiParam(name="parameterA",value=Parameters "A")
 public void path(@PathVariable String parameterA, String parameterB)
Copy the code

Where name specifies the name of the parameter, this is done by string without IDE refactoring support. The way javadoc specifies it, with IDE refactoring support, changes the variable names in Javadoc when you rename them. Such as:

/** * path variable * @param parameterA parameterA * @param parameterB parameterB */ @postmapping ("/path/{parameterA}/{parameterB}")
    public void path(@PathVariable String parameterA, String parameterB)
    {
    }
Copy the code

Using the RestDoc library, the code is as follows:

/** * complex object in body */ @postmapping ("/body/complex"Public void complex(@requestbody ParameterA obj) {} /** * path variables * @param ParameterA ParameterA * @param parameb parameterB */ @PostMapping("/path/{parameterA}/{parameterB}")
    public void path(@PathVariable String parameterA, String parameterB)
    {
    }
Copy the code

The effect is as follows:

use

Warehouse address: github.com/Willing-Xyz… Online example: www.willingxyz.cn:8084/swagger-ui/…

First, configure poM and RestDocConfig

In SpringBoot, add dependencies:

<dependency> <groupId>cn.willingxyz.restdoc</groupId> <artifactId>RestDocSpringSwagger3</artifactId> < version > 0.2.0.0 - beta1 < / version > < / dependency >Copy the code

For JavaConfig, the configuration is as follows:

@Bean
RestDocConfig _swaggerConfig(a)
{
    return RestDocConfig.builder()
            .apiTitle("rest doc title")
            .apiDescription("rest doc desc")
            .apiVersion("api version")
        // .fieldPrefix("_")
            .packages(Arrays.asList(""))
            .build();
}
Copy the code

The basis of packages offered to scan the package name, such as packages (arrays.aslist (” cn. Willingxyz. Restdoc. Springswagger3. Examples “))

FieldPrefix indicates the fieldPrefix. Because javadoc is retrieved from the field, get, and set methods, if the field has a prefix, it needs to be set with fieldPrefix, otherwise the Javadoc will not be retrieved. Such as:

public class Response {
    /** * name javadoc */
    private String _name;
    public String getName(a) {
           return _name;
    }
    public void setName(String name) { _name = name; }}Copy the code

The Name attribute corresponds to the field _name, so fieldPrefix should be set to.fieldprefix (“_”).

Second, add the following dependencies in the project where javadoc needs to be generated:

<! -- Annotation processor --> <dependency> <groupId>com.github.therapi</groupId> < artifactId > therapi - runtime - javadoc - scribe < / artifactId > < version > 0.9.0 < / version > the < scope > provided < / scope > < / dependency >Copy the code

After starting the application, go to http://host/swagger-ui/index.html to browse

For details, see RestDocSpringExamples.

The principle of

Json files for Javadoc are generated at compile time through the annotation processor. Read the generated Javadoc file at run time.