XDoc generates API documentation based on Java comments
<!--Adding maven dependencies-->
<dependency>
<groupId>com.github.treeleafj</groupId>
<artifactId>spring-boot-starter-xDoc</artifactId>
<version>1.1.0</version>
</dependency>
@EnableXDoc //<--- Add this note to enable XDOC online HTML documents
@SpringBootApplication
public class TestApplication {
public static void main(String[] args) {
SpringApplication.run(TestApplication.class, args);
}
}
#在application.propertiesConfigure the location of the project source code, directly in the project start, if it is a single module of the maven project, the default can not be configured
xdoc.enable=true #Start XDoc or not, default is true, production environment suggest change to false.
xdoc.sourcePath=F:/java/project/xDoc/samples/sample-springboot/src/main/java # sourcePath, multiple paths separated by commas
xdoc.title=User Center Interface Document #For configuring document page title
xdoc.version=1.0 #Identifies the version number of the interface document
Test code (Controller)
/**
* User Moudle
*
* @author treeleaf
* @date 2017-03-03 10:11
*/
@Controller
@RequestMapping("api/user")
public class UserController {
/**
* Login
*
* @param username Usernaem|compulsory fields
* @param password password
* @return Basic information of current registered users
* @resp code Return code(0000 means successful login,others means failed)|string|Required
* @resp msg login info|string
* @resp username The username returned after successful login|string
*/
@ResponseBody
@PostMapping("login")
public Map<String, String> login(String username, String password) {
Map<String, String> model = new HashMap<>();
model.put("code", "0000");
model.put("msg", "Login success");
model.put("username", username);
return model;
}
/**
* 用户注册
*
* @param user :username Username|Required
* @param user :password Password
* @return Basic information of the user generated after registration
* @respbody {"id":"123","password":"123456","username":"admin"}
* @see User
*/
@ResponseBody
@RequestMapping(value = "register", method = {RequestMethod.POST, RequestMethod.PUT})
User register(User user) {
user.setId(UUID.randomUUID().toString());
return user;
}
}
The last visit http://localhost:8080/xdoc/index.html directly
Two: Offline documentation
html:
/**
* Generate offline interface files in HTML format
*/
@Test
public void buildHtml() throws Exception {
/**NOTICE!!!! The path must be able to scan the source code project path, the implementation of the file generated to open the interface directory does not indicate that not scanned, please prioritize to confirm their own incoming path is correct!!!! */
FileOutputStream out = new FileOutputStream(new File(userDir, "api.html"));
XDoc xDoc = new XDoc(new File("F:/java/project/xDoc/samples/sample-springboot/src/main/java"), new SpringWebHttpFramework());
xDoc.build(out, new HtmlForamt());
}
Markdown:
/**
* Generate offline interface files in Markdown format.
*/
@Test
public void buildMarkdown() {
/**Note!!!! The path must be able to scan the source code project path, the implementation of the generated markdown if there is no interface content, that is not scanned, please prioritize to confirm that their incoming path is correct!!!!*/
ByteArrayOutputStream out = new ByteArrayOutputStream();
XDoc xDoc = new XDoc(new File("F:/java/project/xDoc/samples/sample-springboot/src/main/java"), new SpringWebHttpFramework());
xDoc.build(out, new MarkdownFormat());
System.out.println(out.toString());
}
Usage of comment tag:
The @title interface title. If you don’t add this, the default is to read the description on the first line of the interface comment
“Parameter name parameter describes |(parameter type)|(mandatory)”, in which “parameter type” is optional and default is String, “mandatory” is optional and default is non-mandatory. The values of “mandatory” include mandatory (Y) and non-mandatory (N), and the commonly used format is as follows: Username username username username username username username username username username username username | is required or username username username |Y username username | is not required or username username |N username username |String username username |String| is required
For IDEA, using Java’s own @param annotation is an error if the parameter name above is not on the current method argument. To solve this problem,XDoc supports putting a colon before the annotation parameter name to avoid detection of IDEA, such as: :username username or user :username username
When @paramobj feel that the parameter itself is in a Dto, but it is troublesome to add @param one by one, we can use @paramobj to specify the Dto object. The usage is the same as @see, but @paramobj supports multiple interface methods. At the same time,@param is mixed with @paramobj, when some attribute name in @paramobj object conflicts with the parameter name of @param, it will take the @param first. Accountcontroller.java in samples that can be referenced is used
@resp specifies the parameters to return in the same format as @param
@Respbody specifies the demo that will return the data, supports formatting json data only for presentation purposes, and USES userController.java in reference samples
@see specifies the returned reference object, similar to @paramobj, but one is incoming and one is out, only one @see can appear in a method, meanwhile, when mixed with @resp, the attribute name conflicts, which is @resp, accountcontroller.Java in reference samples is used
@return returns a description of the information, which is plain text and used for presentation only
@ IgnoreApi this annotation, not on the annotation, used to indicate which interfaces do not need to generate documentation
Read More:
- Mongodb java version 3.X, prompt “XXX (an encryption algorithm) is not available” when there is a user name and password
- [Solved] Circular view path [index]: would dispatch back to the current handler URL [] again. Che
- Upload file error analysis standardmultiparthttpservletrequest
- JAVA: How to use the third-party font library method (using the third-party TTF / TTC font library method)
- Spring MVC uses Ajax to submit requests asynchronously to complete login
- JAVA: How to Read JSON Format Data (Web Game Development)
- [Solved] Tomcat Error: org.apache.tomcat.util.digester.Digester.fatalError Parse fatal error at line [40] column [36]
- [Solved] javax.crypto.BadPaddingException: Decryption error
- The problem of date format conversion between springboot and front end
- Mybatis single parameter pass in exception (How to Fix)
- [Solved] java.lang.IllegalStateException: Cannot call sendRedirect() after the response has been committed
- How to Solve JAR pack error: Error resolving template [/userInfo], template might not exist or might not be accessib
- [Solved] “status“:405,“error“ Request method ‘POST‘ not supported“
- Extracting JDBC tool class: JDBC utils
- Java implementation of inputsteam to Base64
- Java will convert Excel to list set or JSON, export excel file to local, excel import and export, easyexcel tool class
- How to Solve the Primary Key of mybatisPlus Inserted Data is too Large Issue
- JAVA: Controller exception handling
- [Solved] JSON parse error: Cannot deserialize instance of `java.util.ArrayList<..> out of START_OBJECT token;
- JAVA: How to Convert PDF from Color to Grayscale