SpringBoot Generates JavaDoc

 1. Introduction      

With the development of microservices and the scale of the web application, it is easy to encounter codes with numerous classes and packages. Therefore, having a good habit of illustrating the entities and controllers clearly in a project is crucial for efficient application development. Besides, as the frontend-backend-separated programming style is becoming mainstream, our backend code should be as straightforward as possible for front-end programmers to read. Today's tutorials will introduce using OpenAPI to generate JavaDocs in SpringBoot.

2. Details

First, we need to add our OpenAPI to obtain practical classes in our maven pom file. 1.6.11 is the latest version as this tutorial comes out. Actually, with the latest feature of OpenAPI, there aren't many set up for us to handle anymore. A beautifully designed JavaDoc file will be generated automatically.

<dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-ui</artifactId>
      <version>1.6.11</version>
   </dependency>

To test our project, I have prepared a simple MVC program with an entity bean called the SpaceCraft and a controller bean.

@Data
@NoArgsConstructor
@AllArgsConstructor
@Builder
public class SpaceCraft {

    private String name;

    private Integer weight;

    private String description;

    private Integer numberOfCrew;
}

(Lombok is also used in this project for shortened codes)

@Tag(name = "星球飞船的控制器")
@RestController
public class SpaceCraftController {

    private List<SpaceCraft> crafts = new ArrayList<>();

    @GetMapping("/spacecraft")
    @Operation(summary = "获取目前可得的飞船")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "Found the book",
                    content = { @Content(mediaType = "application/json",
                            schema = @Schema(implementation = SpaceCraft.class)) }),
            @ApiResponse(responseCode = "400", description = "Invalid id supplied",
                    content = @Content),
            @ApiResponse(responseCode = "404", description = "Book not found",
                    content = @Content) })
    public List<SpaceCraft> returnSomeCraft(){
        crafts.add(new SpaceCraft("东方号",20,"最大的战列舰",5));
        return crafts;
    }

    @PostMapping("/spacecraft")
    public SpaceCraft createCraft(@RequestParam String craftName,
                              @RequestParam Integer crew,
                              @RequestParam Integer weight,
                              @RequestParam String description){
        SpaceCraft spaceCraft = SpaceCraft.builder().description(description).weight(weight).numberOfCrew(crew)
                .name(craftName).build();
        crafts.add(spaceCraft);
        return spaceCraft;

    }
}

Here, the tag annotation indicates the name of the whole controller, while the "operation" annotation states the name of a single controller. The "ApiResponse" annotation will display the result of a controller, including the return's type and required parameters. Although the OpenApi will generate files even if we don't write any of these annotations, it is better for us to make it clear with more details.

@Bean
	public OpenAPI springShopOpenAPI() {
		return new OpenAPI()
				.info(new Info().title("SpringShop API")
						.description("Spring shop sample application")
						.version("v0.0.1")
						.license(new License().name("Apache 2.0").url("http://springdoc.org")))
				.externalDocs(new ExternalDocumentation()
						.description("SpringShop Wiki Documentation")
						.url("https://springshop.wiki.github.org/docs"));
	}

Finally, there is some information we can add to our JavaDoc file, including version, description, author etc. Usually, this information is written in the application class. 

Our JavaDoc file is officially generated! After starting the server, we can visit [URL]:[port]/swagger-ui/index.html to see the result!