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 返回信息的描述,內容為純文本,僅用於展示