服务端开发人员在开发完接口以前(或以后)还有一项重要的工作内容——编写接口文档。个人认为这是一件很繁琐的事情,前两天听同事推荐一个框架Swagger,只需几行注解便可解决这个让人头疼的问题,这里先看一下调试好的页面截图:
上图展示的是接口列表(如果未声明post或get提交方式则展示两次——一次get、一次post -_-!!),右侧是接口功能描述。
上图展示的是接口中定义的参数名、是否必输项、参数描述、参数类型等,可以直接输入参数进行接口测试,比较方便。
接下来再说说项目的配置(我这里是用maven管理项目,之前已引入springmvc相关依赖):
1、引入swagger相关jar;
2、application.xml文件中配置bean,最后一行是swagger-ui相关配置;
3、swagger相关配置类
4、在swagger官网下载页面相关文件复制到项目中(注意index.html中有个默认URL需要修改成自己的项目URL),我这里用的是老版本,swagger新版本的目录结构可能与这个不一样。
5、最后一步就是在控制层的注解了,这个框架不影响源代码业务逻辑,只需添加注解即可;
感觉要是支持导出word格式的接口文档就更完美了,然而我这个版本的没找着,不知道是不是可以通过其他方式配置。