授权协议: MIT
开发语言: Java
操作系统: 跨平台
收录时间: 2018-07-13
提 交 者: 风里的叶子

XDoc, 是基于Java语言编写,提供将Java方法上的注释转成接口文档的工具.不同于sun doc生成的Java文档, XDoc只专注于对外接口层的文档转译, 基于原有的sun doc注解,加上扩展的一些,为使用者提供了更加丰富的注释功能,让更加快捷的生成接口文档,不需要再打开word等文档,按照繁琐的方式,将接口文档一点点加上去.

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 demo

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 返回信息的描述,内容为纯文本,仅用于展示

  • @IgnoreApi 这个是注解,不是放在注释上的,用于标注哪些接口不需要生成接口文档

展开阅读全文

代码

的 Gitee 指数为
超过 的项目

XDoc-Java 的相关博客

java -d . **.java 与 java **.java 的区别

如何在命令行模式下运行带包的java文件 https://blog.csdn.net/lytor/article/details/17048361 javac,使用"-d ."与省略-d的...

java JDBC

JDBC(Java DataBase Connectivity, java数据库连接)是一种用于执行SQL语句的Java API,可以为多种关系数据库提供统一访问,...

Java ThreadLocal

Java的ThreadLocal变量用来创建线程本地变量。我们知道,一个对象上的所有线程,都会共享该对象的变量,所以这些共享的变量不...

Java的ThreadLocal

简介 ThreadLocal是一个本地线程副本变量工具类。主要用于将私有线程和该线程存放的副本对象做一个映射,各个线程之间的变量互...

java 之ThreadLocal

java 之ThreadLocal

java_jdbc

jdbc:数据库连接,是一种用于执行SQL语句的Java API,可以为多种关系数据库提供统一访问,它由一组用Java语言编写的类和接口组...

Java JVM

Tomcat本身不能直接在计算机上运行,需要依赖于硬件基础之上的操作系统和一个Java虚拟机。Tomcat的内存溢出本质就是JVM内存溢...

Java_JDBC

JDBC-ODBC桥连接形式:利用微软提供的ODBC进行数据库链接,然后利用JDBC访问ODBC的函数库,实现数据操作 流程:程序>JDBC>ODB...

java ThreadLocal

每次看到这玩意熟悉,就是想不起来什么东西,看了才知道是啥玩意,就写个笔记强化一下记忆。 private ThreadLocal threadLoca...

XDoc-Java 的相关问答

还没有任何问答,马上提问

评论 (6)

加载中
我想问下这个和apidoc有啥区别?
07/16 00:24
回复
举报
测试模块的请求地址怎么配置啊
01/06 16:29
回复
举报
风里的叶子软件作者
直接是本地localhost
01/22 10:39
回复
举报
如果返回结果能够基于程序自动响应的结果,而不是手动填写,就更好了,更省事一些。
2018/07/18 08:54
回复
举报
如果是一个对象 里面的字段也能解析吗?
2018/07/13 19:59
回复
举报
风里的叶子软件作者
能滴
2019/12/08 17:31
回复
举报
更多评论
6 评论
56 收藏
分享
返回顶部
顶部