接口文檔自動工具

swammdoc 接口文檔自動生成工具

如圖：

1. 團隊協做離不開約定，規範，最先咱們用word，excel編寫接口文檔，如今有了開源，涌現了一批接口文檔管理平臺， rap ， 小幺雞， apiManager等等， 有了更友好結構化展現，版本歷史， mock等等好用功能。

2. 問題來了， 寫好了代碼怎麼維護到api管理平臺上，只能手工操做。或者自已定義一套註解庫，用來標識請求參數，返回參數，這樣對代碼的侵入性又有點太強了。

3. javadoc 這個功能彷佛被咱們怱略了，連身邊朋友都沒見有人在用這個。javadoc 提供了很強勁的分析源碼的功能，參數類型， 返回類型， 泛型等等，通通能夠取到， 請求參數，返回參數出現循環引用問題， 目前限制到4層。

4. 第一個版本對接了rap ， 後來在使用過程當中，rap愈來愈慢，最後遷到小幺雞，原來內部使用shell腳本執行， 這一個版本使用maven 插件的形式，如今還處理初級階段，有興趣的朋友能夠修改，本身使用

5. 有興趣的朋友能夠了解一下javadoc的使用方式， 這個工具使用也是創建在javadoc之上，maven插件也是在maven javadoc 插件的基礎上

使用方法

1. maven 插件, 在pom裏增長該插件（目前該插件尚未發佈到中央倉庫， 須要的小夥伴clone下來， mvn install 就ok了）， 執行 mvn javadoc:javadoc

<build>
        <plugins>
            ...
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-javadoc-plugin</artifactId>
                <version>3.0.0-M1</version>
                <configuration>
                    <!-- debug 模式， 在target目錄，生成javadoc 執行文件方便調試 -->
                    <debug>true</debug>
                    <doclet>io.swammdoc.doc.Doclet</doclet>
                    <docletArtifact>
                        <groupId>io.swammdoc</groupId>
                        <artifactId>doclet</artifactId>
                        <version>1.0.0</version>
                    </docletArtifact>
                    <useStandardDocletOptions>false</useStandardDocletOptions>
                    <additionalparam>
                          <!-- 這裏是額外的參數，對應javadoc 命令行 -tag 參數，目前尚沒有發如今更好的方式傳參給自定義的Doclet； class: 指定須要生成接口的類， projectId: 指定接口文檔小幺雞工程id， host：小幺雞host   -->
                         -tag class=UserController;projectId=1hW7GG48X8;host=http://doc.xxxx.com
                    </additionalparam>
                    <show>private</show>
                    <sourcepath>src/main/java</sourcepath>
                    <!-- 指定要掃描的包名 -->
                    <subpackages>com.3d.projectName.app</subpackages>
                </configuration>
            </plugin>
        </plugins>
    </build>

2. 代碼描述格式

/**
* 用戶實體
*/
public class User {
    
    /**
    * 姓名 (註釋)
    */
    private String name;
    /**
    * 年齡(註釋)
    */
    private Integer age;
    /**
    * @ignore  (帶有此標籤的被忽略)
    */
    private String remark;
    .... getter setter
}

public class UserQuery {
    /**
    * 姓名 (註釋)
    */
    private String name;
    /**
    * 年齡(註釋)
    */
    private Integer age;
    /**
    * 備註
    */
    private String remark;
    .... getter setter
}

/**
*  
*/
@RequestMapping("/user")
@RestController （接口是spring mvc, 必須是controller,  @RestController 或者@Controller）
public class UserController {
        /*
        * @title 用戶列表接口 （接口名稱， 沒有@title 標籤， 方法名稱優先級：@title 標籤 > 方法註釋 > 方法名）
        */
        public List<User> list(UserQuery query) {
               ...
            // 默認狀況下把UserQuery 全部屬性看成請求參數， UserDto 全部屬性做爲返回參數，
        }


        /**
        * 用戶保存
        * @param user @name
        * @param user @age
        **/
        public List<Integer> save(User user) {
               ...
            // 若是有指定參數， 則按照指定的參數做爲請求參數
        }
            
}

3. spring mvc 已經支持， dubbo 協議在完善中

github地址：https://github.com/chengpan168/swamm