使用swagger做为restful api的doc文档生成

• 本文做者：@Ryan Miao
• 本文连接：https://www.cnblogs.com/woshimrf/p/swagger.html
• 版权声明： 本博客全部文章除特别声明外，均采用 CC BY-NC-SA 3.0 许可协议。转载请注明出处！

目录

初衷
swagger介绍
在dropwizard中使用
在spring-boot中使用
配置
4.设定访问API doc的路由
6. 设置在生产环境关闭swagger
参考：

初衷

记得之前写接口，写完后会整理一份API接口文档，而文档的格式若是没有具体要求的话，最终展现的文档则彻底决定于开发者的心情。也许多点，也许少点。甚至，接口老是须要适应新需求的，修改了，增长了，这份文档维护起来就很困难了。因而发现了swagger，自动生成文档的工具。

swagger介绍

首先，官网这样写的：

Swagger – The World's Most Popular Framework for APIs.

由于自强因此自信。swagger官方更新很给力，各类版本的更新都有。swagger会扫描配置的API文档格式自动生成一份json数据，而swagger官方也提供了ui来作一般的展现，固然也支持自定义ui的。不过对后端开发者来讲，能用就能够了，官方就能够了。

最强的是，不只展现API，并且能够调用访问，只要输入参数既能够try it out.

效果为先，最终展现doc界面，也能够设置为中文：

在dropwizard中使用

详细信息见另外一篇在dropwizard中使用Swagger

在spring-boot中使用

之前老是看各类博客来配置，此次也不例外。百度了千篇一概却又各有细微的差异，甚至时间上、版本上各有不一样。最终仍是去看官方文档，终于发现了官方的sample。针对于各类option的操做彻底在demo中了，因此clone照抄就能够用了。

github sample源码

配置

1.须要依赖两个包：

第一个是API获取的包，第二是官方给出的一个ui界面。这个界面能够自定义，默认是官方的，对于安全问题，以及ui路由设置须要着重思考。

2.swagger的configuration

须要特别注意的是swagger scan base package,这是扫描注解的配置，即你的API接口位置。

固然，scan package 也能够换成别的条件，好比：

3.在API上作一些声明

案例：

4.设定访问API doc的路由

在配置文件中，application.yml中声明：

这个path就是json的访问request mapping.能够自定义，防止与自身代码冲突。

API doc的显示路由是：http://localhost:8080/swagger-ui.html

若是项目是一个webservice，一般设定home / 指向这里：

5.访问

就是上面的了。可是，注意到安全问题就会感受困扰。首先，该接口请求有几个：

除却自定义的url，还有2个ui显示的API和一个安全问题的API。关于安全问题的配置还没去研究，但目前发现一个问题是在个人一个项目中，全部的url必须带有query htid=xxx,这是为了sso portal验证的时候须要。这样这个几个路由就不符合要求了。

若是不想去研究安全问题怎么解决，那么能够自定ui。只须要将ui下面的文件拷贝出来，而后修改请求数据方式便可。

6. 设置在生产环境关闭swagger

具体参考 http://www.cnblogs.com/woshimrf/p/disable-swagger.html