XDoc-Java 1.1.0 发布,Java 纯注释生成接口文档工具
1.1.0版本更新内容:
1. 代码结构重构,升级依赖包版本,同时各demo案例移动到smaples目录下
2. 增加对JFinal的支持
3.应大众要求,增加@paramObj注释标签支持
4.优化markdown格式输出
XDoc 基于Java注释的接口文档工具
- 基于java注释生成接口文档-对代码无侵入,无需注解,纯代码注释
- 支持SpringWeb, SpringBoot, JFinal
- 文档输出格式支持markdown和离线/在线html等
为何使用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文档 @SpringBootApplication public class TestApplication { public static void main(String[] args) { SpringApplication.run(TestApplication.class, args); } }
#在application.properties配置项目源码的位置,直接在项目里启动时,如果是单模块的maven项目,默认可以不配置 xdoc.enable=true #是否启动XDoc,默认是true,生产环境建议改为false xdoc.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格式的接口文档 */ @Test public 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格式的接口文档 */ @Test public 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
现有注释标签用法:
-
@title 接口标题,如果不加这个,默认读的是接口注释上第一行的描述内容
-
@param 接口入参, 格式为: "参数名 参数描述|(参数类型)|(是否必填)" 其中"参数类型"可不填,默认是
String
, "是否必填"可不填,默认为非必填, "是否必填"的取值有必填(Y)
,非必填(N)
,具体常用的格式如下: username 用户名 username 用户名|必填或者
username 用户名|Y username 用户名|非必填或者
username 用户名|N username 用户名|String username 用户名|String|必填针对IDEA的在使用Java自身的@param注释注解时,如果上面的参数名在当前方法入参上是没有的,是会提示错误的,为了解决这种问题,XDoc支持在注释的参数名称前面加上
冒号:
来避开IDEA的检测,如: :username 用户名或者
user :username 用户名 -
@paramObj 当觉得入参本身就在一个Dto中,但是要一个个@param去加会比较麻烦时,可以用@paramObj指定入参的Dto对象,用法同@see,但是@paramObj支持一个接口方法出现多个,同时,@param与@paramObj混用,@paramObj对象中的某个属性名与@param的参数名冲突时,会优先以@param的为准, 使用可参考samples中的AccountController.java
-
@resp 指定返回的参数,格式同@param
-
@respbody 指定返回数据的demo,暂只支持对json数据进行格式化,仅用于展示,使用可参考samples中的UserController.java
-
@see 指定返回的出参对象,类似@paramObj,不过一个是入参,一个是出参,一个方法只能出现一个@see,同时,跟@resp混用时有属性名冲突,以@resp的为准, 使用可参考samples中的AccountController.java
-
@return 返回信息的描述,内容为纯文本,仅用于展示
低调大师中文资讯倾力打造互联网数据资讯、行业资源、电子商务、移动互联网、网络营销平台。
持续更新报道IT业界、互联网、市场资讯、驱动更新,是最及时权威的产业资讯及硬件资讯报道平台。
转载内容版权归作者及来源网站所有,本站原创内容转载请注明来源。
- 上一篇
12月09日云栖号头条:人脸识别遍地开花,谁来守护我们的脸;人工智还能预测地震?
今日最新云头条快讯:2019年被视为5G商用元年;地震预测的目标从来都不是预测慢地震。相反,它是为了预测突然发生的、对生命和肢体构成危险的灾难性地震;,一起来看最新的资讯: 地又震了,人工智还能预测地震? 对于机器学习的方法来说,这提出了一个矛盾:最大的地震,地震学家最希望能够预测的地震,同时也是最罕见的。机器学习算法如何获得足够的训练数据来预测它们?在最好的情况下,对大地震的预测可能会有数周、数月或数年的时间限制。虽然预测可能无法用于协调地震前夕的大规模疏散,但可以增加公众的准备期,帮助政府官员有针对性地改造不安全的建筑,并以其他方式减轻灾难性地震的危害。 从“芯”看5G 5G时代,除了考验芯片设计能力,生态系统建设与运营也将成为移动终端芯片公司所面临的重要挑战。全球超过40家运营商已经局部部署了5G网络,超过40家终端厂商宣布推出5G终端。但如何让5G从地图上的一个个点缀,规模化扩展至全球,是当前移动通信产业的头等大事。 中美日韩处于5G商用进度第一梯队 根据美国无线通信和互联网协会(CTIA)2018年4月发布的报告,中国、韩国、美国、日本已成为全球5G的主要玩家,其中中国的5G...
- 下一篇
MISP 2.4.119 发布,开源威胁情报和共享平台
MISP 2.4.119已发布,该版本的一些更新内容如下: 漏洞 CVE-2019-19379 已修复 数据库诊断 改进了MISP中的时间戳过滤。attribute_timestamp 标志已添加到 attribute / restSearch。现在,MISP 中存在四个可以使用的时间戳过滤器。 API弃用。MISP 大型重构的准备工作正在进行中,这次该团队添加了一个新系统,该系统将开始跟踪 MISP 中已弃用的端点并警告用户其状态。 导出API重构。所有已弃用的导出 API(例如 / events / hids 导出,/ events / stix 或 / events / xml)都已重构,现在正在使用 restSearch。 瞄准同步 misp-modules 版本 2.4.119 MISP 模块已得到改进,并在扩展,导出和导入中添加了许多新模块。 详细信息:https://github.com/MISP/MISP/releases/tag/v2.4.119
相关文章
文章评论
共有0条评论来说两句吧...
文章二维码
点击排行
-
Docker使用Oracle官方镜像安装(12C,18C,19C)
- Springboot2将连接池hikari替换为druid,体验最强大的数据库连接池
- CentOS8编译安装MySQL8.0.19
- Docker快速安装Oracle11G,搭建oracle11g学习环境
- SpringBoot2配置默认Tomcat设置,开启更多高级功能
- MySQL8.0.19开启GTID主从同步CentOS8
- CentOS7,8上快速安装Gitea,搭建Git服务器
- Jdk安装(Linux,MacOS,Windows),包含三大操作系统的最全安装
- SpringBoot2编写第一个Controller,响应你的http请求并返回结果
推荐阅读
最新文章
- CentOS8编译安装MySQL8.0.19
- CentOS6,CentOS7官方镜像安装Oracle11G
- SpringBoot2整合Thymeleaf,官方推荐html解决方案
- 设置Eclipse缩进为4个空格,增强代码规范
- CentOS7,8上快速安装Gitea,搭建Git服务器
- Windows10,CentOS7,CentOS8安装MongoDB4.0.16
- CentOS7安装Docker,走上虚拟化容器引擎之路
- CentOS6,7,8上安装Nginx,支持https2.0的开启
- CentOS7编译安装Cmake3.16.3,解决mysql等软件编译问题
- Docker安装Oracle12C,快速搭建Oracle学习环境