XDoc, 是基于Java語言編寫,提供將Java方法上的注釋轉(zhuǎn)成接口文檔的工具．不同于sun doc生成的Java文檔, XDoc只專注于對外接口層的文檔轉(zhuǎn)譯, 基于原有的sun doc注解,加上擴展的一些,為使用者提供了更加豐富的注釋功能,讓更加快捷的生成接口文檔,不需要再打開word等文檔,按照繁瑣的方式,將接口文檔一點點加上去.

XDoc 基于Java注釋的接口文檔工具

基于java注釋生成接口文檔-對代碼無侵入,無需注解,純代碼注釋
支持SpringWeb, SpringBoot, JFinal
文檔輸出格式支持markdown和離線/在線html等

為何使用XDoc?

減少外部接口文檔的另外編寫,在編碼過程就一起完成,減少外部維護工作量
修改代碼時,少掉翻看外部接口文檔的過程,直接看代碼注釋
接口文檔同版本管理一起,可方便回退以及多環(huán)境多版本
難道標準的注釋不應(yīng)該作為企業(yè)項目的必須規(guī)范嗎?如果你的規(guī)范里沒有接口這塊的,那么,還不補上?如果補上的還能幫你生成文檔,何樂而不為?

如何使用?

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,生產(chǎn)環(huán)境建議改為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 {
    /**注意!!!路徑必須是要能掃描到源碼工程的路徑,執(zhí)行生成的文件打開沒有接口目錄,說明沒掃描到,請優(yōu)先確認自己傳入的路徑是否正確!!!*/
    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() {
    /**注意!!!路徑必須是要能掃描到源碼工程的路徑,執(zhí)行生成的markdown如果沒有接口內(nèi)容,說明沒掃描到,請優(yōu)先確認自己傳入的路徑是否正確!!!*/
	
    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

現(xiàn)有注釋標簽用法:

@title 接口標題,如果不加這個,默認讀的是接口注釋上第一行的描述內(nèi)容
@param 接口入?yún)? 格式為: "參數(shù)名參數(shù)描述|(參數(shù)類型)|(是否必填)" 其中"參數(shù)類型"可不填,默認是String, "是否必填"可不填,默認為非必填, "是否必填"的取值有必填(Y),非必填(N),具體常用的格式如下: username 用戶名 username 用戶名|必填 或者 username 用戶名|Y username 用戶名|非必填 或者 username 用戶名|N username 用戶名|String username 用戶名|String|必填

針對IDEA的在使用Java自身的@param注釋注解時,如果上面的參數(shù)名在當前方法入?yún)⑸鲜菦]有的,是會提示錯誤的,為了解決這種問題,XDoc支持在注釋的參數(shù)名稱前面加上冒號:來避開IDEA的檢測,如: :username 用戶名 或者 user :username 用戶名
@paramObj 當覺得入?yún)⒈旧砭驮谝粋€Dto中,但是要一個個@param去加會比較麻煩時,可以用@paramObj指定入?yún)⒌腄to對象,用法同@see,但是@paramObj支持一個接口方法出現(xiàn)多個,同時,@param與@paramObj混用,@paramObj對象中的某個屬性名與@param的參數(shù)名沖突時,會優(yōu)先以@param的為準, 使用可參考samples中的AccountController.java
@resp 指定返回的參數(shù),格式同@param
@respbody 指定返回數(shù)據(jù)的demo,暫只支持對json數(shù)據(jù)進行格式化,僅用于展示,使用可參考samples中的UserController.java
@see 指定返回的出參對象,類似@paramObj,不過一個是入?yún)?一個是出參,一個方法只能出現(xiàn)一個@see,同時,跟@resp混用時有屬性名沖突,以@resp的為準, 使用可參考samples中的AccountController.java
@return 返回信息的描述,內(nèi)容為純文本,僅用于展示
@IgnoreApi 這個是注解,不是放在注釋上的,用于標注哪些接口不需要生成接口文檔

XDoc-Java基于 Java 的代碼注釋