In Java development, automatically generating API documents is a very practical function, which can help developers quickly understand the classes, methods, parameters and other information in the project. The following are several common ways to automatically generate API documents in Java:
1. Using Javadoc
Javadoc is a tool that comes with Java, which can generate API documents from comments in Java source code.
Code Comment Specification
In Java code, comments in specific formats are used to describe information such as classes, methods, parameters, etc. For example:
/**
* This is a sample class that demonstrates the use of Javadoc.
*
* @author Developer Name
* @version 1.0
*/
public class ExampleClass {
/**
* This is an example method for calculating the sum of two integers.
*
* @param a First integer
* @param b Second integer
* @return The sum of two integers
*/
public int add(int a, int b) {
return a + b;
}
}In the above code, the class annotation is wrapped using /** ... */, which contains the class description, author and version information. Method comments also use /** ... */ package, including the method description, parameter description and return value description.
Generate a document
On the command line, enter the directory containing the Java source code and execute the following command to generate the Javadoc document:
javadoc -d doc
Where the -d option specifies the output directory for generating the document, doc is the name of the output directory, and is the Java source file to generate the document. If there are multiple source files, you can list them in turn, or use the wildcard *.java to represent all Java files in the current directory.
View the document
The generated document will be stored in the specified output directory. Open the file in that directory and you can view the generated API document in the browser.
2. Use Swagger
Swagger is a powerful API document generation tool that automatically generates documents for RESTful APIs and supports multiple languages, including Java.
Add dependencies
If you are using the Maven project, add the following dependencies in :
<dependencies>
<!-- Swagger API annotation -->
<dependency>
<groupId></groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- Swagger UI -->
<dependency>
<groupId></groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
</dependencies>
Configure Swagger
Create a configuration class to enable Swagger:
import ;
import ;
import ;
import ;
import ;
import ;
import ..EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis((""))
.paths(())
.build();
}
}In the above code, the @Configuration annotation means that this is a configuration class, and the @EnableSwagger2 annotation enables Swagger. Docket is the core configuration class of Swagger. The controller class and request path to generate the document are selected through the select() method.
Add API annotation
Add Swagger annotations to controller classes and methods to describe API information:
import ;
import ;
import ;
import ;
import ;
@RestController
@RequestMapping("/api")
@Api(value = "Sample API", description = "This is an example API documentation")
public class ExampleController {
@GetMapping("/hello")
@ApiOperation(value = "Get Greetings", notes = "Return to a simple greeting")
public String hello() {
return "Hello, World!";
}
}In the above code, the @Api annotation is used to describe the information of the controller class, and the @ApiOperation annotation is used to describe the information of the method.
View the document
After starting the Spring Boot application, visit http://localhost:8080/ (the port number is modified according to the actual situation), and you can view the generated API document in the browser.
3. Use Spring REST Docs
Spring REST Docs is a tool officially provided by Spring for generating RESTful API documents. It combines test cases to generate documents to ensure the accuracy of the documents.
Add dependencies
If you are using the Maven project, add the following dependencies in :
<dependencies>
<dependency>
<groupId></groupId>
<artifactId>spring-restdocs-mockmvc</artifactId>
<version>2.0.</version>
<scope>test</scope>
</dependency>
</dependencies>
Write test cases and generate documentation
import ;
import ;
import ;
import ;
import ;
import static ;
import static .*;
import static ;
import static ;
@WebMvcTest()
@AutoConfigureRestDocs(outputDir = "target/generated-snippets")
public class ExampleControllerDocumentation {
@Autowired
private MockMvc mockMvc;
@Test
public void shouldReturnDefaultMessage() throws Exception {
(get("/api/hello"))
.andExpect(status().isOk())
.andDo(document("hello",
preprocessRequest(prettyPrint()),
preprocessResponse(prettyPrint())));
}
}In the above code, the REST Docs is automatically configured using the @AutoConfigureRestDocs annotation to generate document fragments in the test cases.
Integrated documentation
Create a file in the src/main/asciidoc directory to integrate the generated document fragment into the AsciiDoc document:
= Sample API Documentation
== Greeting API
include::{snippets}/hello/[]
include::{snippets}/hello/[]
include::{snippets}/hello/[]
Generate HTML documents
Use Asciidoctor or other tools to convert AsciiDoc documents to HTML documents:
asciidoctor -b html5 -a stylesheet= src/main/asciidoc/ -o target/generated-docs/
Through the above methods, you can select the appropriate tools according to the needs and characteristics of the project to automatically generate Java API documents.
This is the end of this article about how Java automatically generates API documents. For more related contents of Java API documents, please search for my previous articles or continue browsing the following related articles. I hope everyone will support me in the future!