swammdoc 接口文档自动生成工具

如图：输入图片说明

团队协作离不开约定，规范，最早我们用word，excel编写接口文档，现在有了开源，涌现了一批接口文档管理平台， rap ，小幺鸡， apiManager等等，有了更友好结构化展示，版本历史， mock等等好用功能。
问题来了，写好了代码怎么维护到api管理平台上，只能手工操作。或者自已定义一套注解库，用来标识请求参数，返回参数，这样对代码的侵入性又有点太强了。
javadoc 这个功能似乎被我们怱略了，连身边朋友都没见有人在用这个。javadoc 提供了很强劲的分析源码的功能，参数类型，返回类型，泛型等等，统统可以取到，请求参数，返回参数出现循环引用问题，目前限制到4层。
第一个版本对接了rap ，后来在使用过程中，rap越来越慢，最后迁到小幺鸡，原来内部使用shell脚本执行，这一个版本使用maven 插件的形式，现在还处理初级阶段，有兴趣的朋友可以修改，自己使用
有兴趣的朋友可以了解一下javadoc的使用方式，这个工具使用也是建立在javadoc之上，maven插件也是在maven javadoc 插件的基础上

使用方法

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>

代码描述格式

/**
* 用户实体
*/
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) {
               ...
            // 如果有指定参数， 则按照指定的参数作为请求参数
        }
            
}

spring mvc 已经支持， dubbo 协议在完善中

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

来源：oschina

链接：https://my.oschina.net/u/591938/blog/760775

标签

javadoc

接口文档自动生成

swammdoc

接口文档自动工具

swammdoc 接口文档自动生成工具

使用方法