在线时间:8:00-16:00
迪恩网络APP
随时随地掌握行业动态
扫描二维码
关注迪恩网络微信公众号
XDoc讨论QQ群:820854691❦ XDoc 基于Java注释的接口文档工具
为何使用XDoc?
如何使用?1.以SpringBoot为例:<!--加入maven依赖--><dependency> <groupId>com.github.treeleafj</groupId> <artifactId>spring-boot-starter-xDoc</artifactId> <version>1.1.0</version></dependency> @EnableXDoc //<--- 加上此注解以便启用XDOC在线HTML文档@SpringBootApplicationpublic class TestApplication { public static void main(String[] args) { SpringApplication.run(TestApplication.class, args); }} #在application.properties配置项目源码的位置,直接在项目里启动时,如果是单模块的maven项目,默认可以不配置xdoc.enable=true #是否启动XDoc,默认是true,生产环境建议改为falsexdoc.sourcePath=F:/java/project/xDoc/samples/sample-springboot/src/main/java #源码路径,多个路径时用英文逗号隔开xdoc.title=用户中心接口文档 #用于配置文档页面标题xdoc.version=1.0 #标识接口文档的版本号 以上准备配置就都做好了 接下来,我们只需要像往常一样写个Controller,并写好注释: /** * 用户模块 * * @author treeleaf * @date 2017-03-03 10:11 */@Controller@RequestMapping("api/user")public class UserController { /** * 登录 * * @param username 用户名|必填 * @param password 密码 * @return 当前登录用户的基本信息 * @resp code 返回码(0000表示登录成功,其它表示失败)|string|必填 * @resp msg 登录信息|string * @resp username 登录成功后返回的用户名|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", "登录成功"); model.put("username", username); return model; } /** * 用户注册 * * @param user :username 用户名|必填 * @param user :password 密码 * @return 注册后生成的用户的基本信息 * @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; }} 写完之后,直接启动项目, 敲入地址: http://localhost:8080/xdoc/index.html 2.如果想生成离线文档怎么办?支持html: /** * 生成离线的HTML格式的接口文档 */@Testpublic void buildHtml() throws Exception { /**注意!!!路径必须是要能扫描到源码工程的路径,执行生成的文件打开没有接口目录,说明没扫描到,请优先确认自己传入的路径是否正确!!!*/ 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: /** * 生成离线的Markdown格式的接口文档 */@Testpublic void buildMarkdown() { /**注意!!!路径必须是要能扫描到源码工程的路径,执行生成的markdown如果没有接口内容,说明没扫描到,请优先确认自己传入的路径是否正确!!!*/ 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());} 如果不是SpringBoot,只是单纯的SpringWeb,或者是JFinal, 如何使用请参考samples目录下demo现有注释标签用法:
|
请发表评论