Swagger使用指南

1:认识Swagger

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的Web服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。

作用:

1.接口的文档在线自动生成。

2.功能测试。

Swagger是一组开源项目,其中主要要项目如下:

1.Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger1.2文档转换成Swagger 2.0文档等功能。

2. Swagger-core:
用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF...)、Servlets和Play框架进行集成。

3. Swagger-js: 用于JavaScript的Swagger实现。

4. Swagger-node-express: Swagger模块,用于node.js的Express
web应用框架。

5.Swagger-ui:一个无依赖的HTML、JS和CSS集合,可以为Swagger兼容API动态生成优雅文档。

6.Swagger-codegen:一个模板驱动引擎,通过分析用户Swagger资源声明以各种语言生成客户端代码。

2:Maven

版本号请根据实际情况自行更改。

3:创建Swagger2配置类

在Application.java同级创建Swagger2的配置类Swagger2

如上代码所示,通过createRestApi函数创建Docket的Bean之后,apiInfo()用来创建该Api的基本信息(这些基本信息会展现在文档页面中)。

4:添加文档内容

在完成了上述配置后,其实已经可以生产文档内容,但是这样的文档主要针对请求本身,描述的主要来源是函数的命名,对用户并不友好,我们通常需要自己增加一些说明来丰富文档内容。

Swagger使用的注解及其说明:

注意:@ApiImplicitParam的参数说明:

例子:

完成上述代码添加上,启动Spring Boot程序,访问:http://localhost:8080/swagger-ui.html

如上图,可以看到暴漏出来的控制器信息,点击进入可以看到详细信息。

两个注意点:

1.paramType会直接影响程序的运行期,如果paramType与方法参数获取使用的注解不一致,会直接影响到参数的接收。

例如:

使用Sawgger UI进行测试,接收不到!

2. 还有一个需要注意的地方:

Conntroller中定义的方法必须在@RequestMapper中显示的指定RequestMethod类型,否则SawggerUi会默认为全类型皆可访问,
API列表中会生成多条项目。

如上图:updatePassword()未指定requestMethod,结果生成了7条API信息。所以如果没有特殊需求,建议根据实际情况加上requestMethod。

5:Swagger UI面板说明

6:参考

http://blog.didispace.com/springbootswagger2/

http://blog.csdn.net/jia20003/article/details/50700736

Swagger官网 :http://swagger.io/

Spring Boot & Swagger UI :http://fruzenshtein.com/spring-boot-swagger-ui/

Github:https://github.com/swagger-api/swagger-core/wiki/Annotations

7:接收对象传参的例子

在POJO上增加

注意:在后台采用对象接收参数时,Swagger自带的工具采用的是JSON传参,测试时需要在参数上加入@RequestBody,正常运行采用form或URL提交时候请删除。

增加header:

现在很多请求需要在header增加额外参数,可以参考getDoctorList()的做法,使用request接收。