接口文档自动工具

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