3.2 【实例】微服务集成Swagger
3.2.1 实例背景
本实例将使用微服务集成Swagger，并在Consul中进行注册，为其他服务的调用做准备。本实例还将创建cloud-user-8083工程和cloud-common-jar工程。cloud-common只作为依赖Jar包存在，并为其他工程提供相应的实体类，不整合Boot或Cloud。限于篇幅本书不再介绍cloud-common工程。若在生产项目中，则应新建cloud-parent工程，规定依赖的版本号，将众多微服务的Maven依赖版本保持一致。
本书在工程命名的时候通常将项目的版本号写在工程名和启动类名里，只是为了测试时在Eclipse的Console控制台中显示更加直观。通常将工程名书写为“项目名-微服务名-端口号”，启动类名书写为“ApplicationMain”或“微服务名+AppMain”，配置文件中的spring.application.name分布式微服务名书写为“项目名-微服务名”等。注意，不可使用下画线“_”，因为下画线在Cloud通信中可能会报错。
3.2.2 编写Swagger依赖
Swagger需要引入springfox-swagger2和springfox-swagger-ui的依赖。pom.xml文件所需增加的部分代码如下。
注意，Server端不需要使用Feign进行依赖，声明式服务调用只需要在Client端进行依赖即可。
3.2.3 编写Swagger配置
创建Swagger2.java文件，Swagger2.java文件用于Swagger的基本配置，代码如下。另外，Spring的YAML资源配置文件与2.3节中的资源配置文件基本相同，不再赘述。
@Configuration注解将Swagger2的相关配置注册到Spring容器中。
@EnableSwagger2注解开启Swagger2的相关注解和功能，开启的相关注解包括Swagger2的@Api和@ApiOperation等。
在Swagger2的配置中，相当于将Docket注册到Spring容器中，Docket是Swagger2的构造器，Swagger是基于Spring MVC构建的，Docket提供合理的默认值和方便的配置方法。Docket对象可配置的参数及释义如表3-1所示。
表3-1 Docket对象可配置的参数及释义
apiInfo可配置的参数及释义如表3-2所示。
表3-2 apiInfo可配置的参数及释义
3.2.4 编写接口与接口处的Swagger配置
为方便观察运行效果，在UserController.java文件中编写部分用于测试的接口。每个接口都只返回一个固定参数并打印相关日志，代码如下。
UserController类定义了3个接口，为了展示运行效果，每个接口都使用Swagger的描述性注解修饰，如下。
@ApiImplicitParams注解：引入其他自定义的@ApiImplicitParam资源。
@ApiImplicitParam注解：强行自定义部分入参资源，也可使Swagger自动生成，如果自定义可多写描述信息。
@ApiOperation注解：描述针对特定路径的操作或HTTP方法。HTTP方法与路径的组合将创建一个唯一的操作。在注解不被定义的情况下Swagger也会运行，但为了给每个接口描述信息，会编写该注解。@ApiOperation注解配置的参数及释义如表3-3所示。
表3-3 @ApiOperation注解配置的参数及释义
3.2.5 当前项目结构
启动类与2.3节中的启动类相同。
图3-1的cloud-user-8083工程依赖于图3-2的cloud-common-jar工程，本实例将运行cloud-user-8083工程，运行后观察Swagger生成的在线文档。
图3-1
图3-2
3.2.6 运行效果
1.运行查看Swagger UI页面
运行后输入Swagger默认的浏览地址：http://localhost:8083/swagger-ui.html，可查看Swagger生成的页面，如图3-3所示。
图3-3
在Swagger UI页面中可观察目前所有Swagger扫描的接口，而且Swagger2.java类中Swagger配置的相关文档注释都作为标题等元素显示在Swagger UI中。
2.观察UserController中被Swagger扫描到的接口
由于getUser1接口的@ApiOperation注解中设置了tags参数“UserController”，所以Swagger默认将该接口设置了自己的分组。从页面上可以看出，如果不设置tags，Swagger会以Controller.class进行默认分组，如图3-4所示。
图3-4
3.观察没有被@ApiOperation注解修饰的接口
虽然没有在ApplicationMain8083.class启动类中编写@ApiOperation，但由于Swagger默认扫描该工程下的全部接口，所以Consul健康检查接口也被写入Swagger UI中，如图3-5所示。
图3-5
如果@RequestMapping注解不标识使用哪种RequestMethod，Swagger中的每个RequestMethod类型都会被写入，但不建议使用这种方式，因为接口太多不容易查询。
4.观察getUser1接口
单击getUser1选项显示该接口的详细列表，包括之前输入的以下相关信息，如图3-6所示。
Implementation Notes：操作详情。
Response Class：响应的HTTP状态码和返回参数类型，返回的参数是User对象。
Parameters中的Value：入参json。
图3-6
单击Model Schema选项，会将需要使用的数据转换为json格式，并复制到Value文本框中，如图3-7所示。也可以自行编写所需要输入的参数。Model Schema也可以自定义格式，以减少一些不必要的内置参数。@ApiOperation注解的response参数输入类型为Class＜？＞，Swagger会将要求的入参Class＜？＞转换成自身所使用的Model Schema，并辅助其作为入参使用。
图3-7
5.调用getUser1接口
更改Parameter入参中的Value后，单击Try it out！按钮即可调用getUser1接口，如图3-8所示。
图3-8
返回结果如图3-9所示。
图3-9
Curl文本框中的内容代表Swagger生成了利用Linux Curl工具调用getUser1接口的命令和调用该接口需要的入参，利用Linux控制台直接复制内容，调用结果如图3-10所示。
图3-10
通过返回的响应体name，调用已经到后台了，后台输出如图3-11所示。
图3-11
注意，Swagger是真实进行调用，如果调用的接口操作数据库，数据库也会直接进行操作。
3.2.7 实例易错点
1.注解中的返回类型
@ApiOperation注解的produces参数写成application/json1，可视化页面如图3-12所示。
图3-12
HTTP无法识别此类型，即使传入参数也会出现相应错误，如图3-13所示。
图3-13
HTTP无法受理这些类型，除非自定义其编码格式。HTTP的传输编码格式如表3-4所示。
表3-4 HTTP的传输编码格式
2.返回值不可加toString（）函数
因为使用@RestController注解，其内部含有@ResponseBody注解，所以可以自动将返回值转化成json类型。若返回时再加上toString（），则Swagger UI无法正常调用。由于调用增加了toString（）的getUser3接口，所报错误如图3-14所示。
图3-14
此处也会产生一个冲突问题，如果用Feign调用其他接口，其他接口若返回toString（）后的参数，Feign相关内容都不会报错，但Swagger会报错。因此为了程序统一，都不加toString（）函数，以避免出现此类错误。
注意，加上toString（）函数，后台不会有任何异常，如图3-15所示。
图3-15
3.Swagger的常见注解
表3-5所示为Swagger的常见注解及释义。
表3-5 Swagger的常见注解及释义
