天天看点

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

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

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

因为自强所以自信。swagger官方更新很给力,各种版本的更新都有。swagger会扫描配置的API文档格式自动生成一份json数据,而swagger官方也提供了ui来做通常的展示,当然也支持自定义ui的。不过对后端开发者来说,能用就可以了,官方就可以了。

最强的是,不仅展示API,而且可以调用访问,只要输入参数既可以try it out.

效果为先,最终展示doc界面,也可以设置为中文:

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

以前总是看各种博客来配置,这次也不例外。百度了千篇一律却又各有细微的差别,甚至时间上、版本上各有不同。最终还是去看官方文档,终于发现了官方的sample。针对于各种option的操作完全在demo中了,所以clone照抄就可以用了。

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

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

当然,scan package 也可以换成别的条件,比如:

案例:

在配置文件中,application.yml中声明:

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

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

如果项目是一个webservice,通常设定home / 指向这里:

就是上面的了。但是,注意到安全问题就会感觉困扰。首先,该接口请求有几个:

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

如果不想去研究安全问题怎么解决,那么可以自定ui。只需要将ui下面的文件拷贝出来,然后修改请求数据方式即可。

3.后续阅读文章:

<a href="http://yukinami.github.io/2015/07/07/%E4%BD%BF%E7%94%A8springfox%E7%94%9F%E6%88%90springmvc%E9%A1%B9%E7%9B%AE%E7%9A%84swagger%E7%9A%84%E6%96%87%E6%A1%A3/">http://yukinami.github.io/2015/07/07/%E4%BD%BF%E7%94%A8springfox%E7%94%9F%E6%88%90springmvc%E9%A1%B9%E7%9B%AE%E7%9A%84swagger%E7%9A%84%E6%96%87%E6%A1%A3/</a>

<a href="http://www.aichengxu.com/view/2500558">http://www.aichengxu.com/view/2500558</a>

唯有不断学习方能改变!

-- <b>Ryan Miao</b>