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
