接口文档自动工具

原创
2016/10/19 16:34
阅读数 1.6K

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>
  1. 代码描述格式
/**
* 用户实体
*/
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) {
               ...
            // 如果有指定参数, 则按照指定的参数作为请求参数
        }
            
}

  1. spring mvc 已经支持, dubbo 协议在完善中

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

展开阅读全文
打赏
0
4 收藏
分享
加载中
更多评论
打赏
0 评论
4 收藏
0
分享
返回顶部
顶部