1、Swagger介绍

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务(http
s://swagger.io/)。 它的主要作用是：

1. 使得前后端分离开发更加方便，有利于团队协作
2. 接口的文档在线自动生成，降低后端开发人员编写接口文档的负担
3. 功能测试 Spring已经将Swagger纳入自身的标准，建立了Spring-swagger项目，现在叫Springfox。通过在 项目中引入Springfox ，即可非常简单快捷的使用Swagger

2、SpringBoot集成Swagger

1. 引入依赖

<dependency> 
	<groupId>io.springfox</groupId> 
	<artifactId>springfox-swagger2</artifactId> 
	<version>2.9.2</version> 
</dependency> 
<dependency> 
	<groupId>io.springfox</groupId> 
	<artifactId>springfox-swagger-ui</artifactId> 
	<version>2.9.2</version>
</dependency>

我们一般在公共的工程中进行配置即可，因为其他微服务工程都直接或间接依赖

2.修改配置文件

   # 开启swagger 
   swagger.enable=true

3.在对应工程的config包中添加一个配置类

@Configuration
// 和配置文件application.propertis中的配置对应
// havingValue 的值如果和配置文件的值相等，就开启swagger
@ConditionalOnProperty(prefix = "swagger",value = {"enable"},havingValue = "true")
@EnableSwagger2  //开启swagger注解支持
public class SwaggerConfiguration {

	@Bean
	public Docket buildDocket() {
		return new Docket(DocumentationType.SWAGGER_2)
				.apiInfo(buildApiInfo())
				.select()
				// 要扫描的API(Controller)基础包
				.apis(RequestHandlerSelectors.basePackage("cn.ittest.xxx"))
				.paths(PathSelectors.any())
				.build();
	}

	private ApiInfo buildApiInfo() {
		Contact contact = new Contact("程序员","","");
		return new ApiInfoBuilder()
				.title("开发平台-用户服务API文档")
				.description("包含用户服务api")
				.contact(contact)
				.version("1.0.0").build();
	}
}

3、Swagger常用注解

在Java类中添加Swagger的注解即可生成Swagger接口文档，常用Swagger注解如下：

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数的描述信息
@ApiModel：用对象来接收参数
@ApiModelProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数的描述信息

@ApiImplicitParam属性：

我们在ConsumerController中添加Swagger注解，代码如下所示：

@RestController
@Api(value = "测试服务的Controller", tags = "Consumer", description = "测试服务API")
public class ConsumerController {

    @ApiOperation("测试是否爱你")
    @PostMapping(path = "/love")
    @ApiImplicitParam(name = "name", value = "姓名", required = true, dataType = "String")
    public String hi(String name) {
        return "我 love " + name;
    }
}

启动后访问 ： http://localhost:端口号/服务名/swagger-ui.html
效果如下：

Swagger生成API文档的工作原理：
1、当服务启动时会扫描到SwaggerConfiguration类
2、在此类中指定了扫描包路径cn.ittext.，会找到在此包下及子包下标记有@RestController注解的controller类
3、根据controller类中的Swagger注解生成API文档