swagger 是一个框架,用于生成、描述、调用和可视化RESTful风格的Web服务。

简单来说,swagger可以用来生成接口文档,方便进行使用。

感谢:http://javatech.wang/index.php/archives/74/,但是有很多不尽人意的地方,我进行了一些补全和修正。

一、实现流程

(1)引入maven依赖

当然其中的很多包都可以换最新版的。

(2)写一个java类,作为配置文件

我新建了一个com.xie.swagger包,写了一个swaggerconfig类。

这个类围绕着SpringSwaggerConfig,是为了读取swagger的配置而建立的,可以修改一些页面的属性。

(3)把这个类放进spring mvc中进行整合

这个步骤是最重要的,也是网上各种文章都没有说清楚的。

1.把swagger配置类放进spring容器中

要注意,一定要放进spring-mvc.xml中,而不是spring.xml中!

虽然同为spring,但是只有在spring-mvc.xml中swagger才能正常工作。

具体情况我也不是太清楚为什么,只要我放在spring.xml中,就配置不好。我也是尝试了很久才试出这个结论…

2.把SpringSwaggerConfig类放进spring容器中

要注意,一定要放进spring-mvc.xml中,而不是spring.xml中!

理由同上。

这个配置文件真的是坑死我了!如果不这样放这两个bean,就会爆出各种noclass,can not Autowired,not found的错误!大多数时间都是在这两个配置上面浪费的!

3.原因猜测如下:

估计是放在spring-mvc.xml才能注入RequestMappingHandlerMapping。

RequestMappingHandlerMapping是针对spring mvc.xml的,而spring.xml则无法注入。

(4)下载swagger-ui组件,放入webapp目录

下载地址:https://github.com/swagger-api/swagger-ui

下载完之后,新建一个swagger文件夹,把dist里面的文件丢进去

很重要的一步:

修改swagger/index.html文件,默认是从连接http://petstore.swagger.io/v2/swagger.json获取api的json,这里需要将url值修改为http://{ip}:{port}/{projectName}/api-docs的形式,{}中的值根据自身情况填写。

(5)允许静态资源访问

因为swagger-ui需要多种静态资源的支持,包括html,css,js,所以有必要配置静态资源的直接访问。

这个方法就多种多样了:

  1. 可以在web.xml中配置<servlet-mapping></servlet-mapping>
  2. 也可以在spring-mvc.xml中配置<mvc:resources location=”” mapping=””></mvc:resources>

我采取的是第一种方式:

(6)注释你的controller

默认注释为@ApiOperation(value = “***”)

这样你的这个接口就会在index.html中标示出来了。

还有更多的配置,在以后将会提及。

(7)实现效果

1

二、总结

如果有好的教程,配置swagger一定会更简单。希望能帮助更多的人少踩swagger这个坑,节省大家的时间。

发表评论

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