springfox/swagger生成api文档

最近的工作内容是做一个后端系统,对前端提供web接口。前后端使用类似restful的api。系统并没有完全使用restful的规范,而是简化为客户端post一段json上来,所有参数都放里面,后端解析后再做处理。

由于两端需要沟通,制定一个统一的接口文档就非常重要。放狗搜了一下,先是选择了swagger。发现略坑,然后搜到springfox,它整合了swagger,提供各种工具。就它了。

由于以前没用过springfox,零零碎碎花了两天时间才搞好。由于项目并没有用springboot也不是普通的那种通过url传参的springmvc,项目是自己用jackson做反序列化,并不是通过配置让spring自动去做,springfox并不支持这种不常见的方式,但已不是项目初期,修改的工作量挺大,最后只好决定把请求参数的对象放到返回参数去,正常的返回参数放200,请求的放201.

要注意的地方:

  1. web.xml需要添加swagger的servlet然后做urlmapping,不然swagger-ui.html和/v2/api-docs显示不出来。
  2. swagger的配置文件要加一个swagger config的bean。
  3. swagger config类是做定制化显示用的。例如版本号,作者信息等等。通过实现多个Docket可以输出多条api路径信息和接口文档。
  4. 使用springfox-staticdocs可实现输出静态api文档。但是有个坑,默认编码并非utf-8,中文会乱码。只好自己实现一个Swagger2MarkupResultHandler,在里面指定编码格式。已提pr,不知他们接不接受。

整个项目示例项目在这里

下一步可以打算开始做自动化api测试了。这篇文章给了我不少启发。

此条目发表在技术分类目录,贴了, , , 标签。将固定链接加入收藏夹。

发表评论

电子邮件地址不会被公开。 必填项已用*标注

您可以使用这些HTML标签和属性: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>