Swagger

官网：https://swagger.io/

一、作用：

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

二、使用

1. 引入依赖

 1 <dependency>
 2   <groupId>io.springfox</groupId>
 3   <artifactId>springfox-swagger2</artifactId>
 4   <version>2.9.2</version>
 5 </dependency>
 6 <dependency>
 7   <groupId>io.springfox</groupId>
 8   <artifactId>springfox-swagger-ui</artifactId>
 9   <version>2.9.2</version>
10 </dependency>

2. 在对应工程application.properties配置

1 # 应用程序名称
2 spring.application.name=consumer-service
3 # 微服务访问路径
4 server.servlet.context-path=/consumer
5 # 开启swagger
6 swagger.enable=true

swagger.enable=true对应的就是Swagger配置类的@ConditionalOnProperty(prefix = "swagger",value = {"enable"},havingValue = "true")

3. 对应工程下的Swagger配置类

 1 import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
 2 import org.springframework.context.annotation.Bean;
 3 import org.springframework.context.annotation.Configuration;
 4 import springfox.documentation.builders.ApiInfoBuilder;
 5 import springfox.documentation.builders.PathSelectors;
 6 import springfox.documentation.builders.RequestHandlerSelectors;
 7 import springfox.documentation.service.ApiInfo;
 8 import springfox.documentation.service.Contact;
 9 import springfox.documentation.spi.DocumentationType;
10 import springfox.documentation.spring.web.plugins.Docket;
11 import springfox.documentation.swagger2.annotations.EnableSwagger2;
12 
13 @Configuration
14 @ConditionalOnProperty(prefix = "swagger",value = {"enable"},havingValue = "true")
15 @EnableSwagger2  //开启swagger注解支持
16 public class SwaggerConfiguration {
17 
18     @Bean
19     public Docket buildDocket() {
20         return new Docket(DocumentationType.SWAGGER_2)
21                 .apiInfo(buildApiInfo())
22                 .select()
23                 // 要扫描的API(Controller)基础包。包扫描
24                 .apis(RequestHandlerSelectors.basePackage("cn.xxx.xxxxxx"))
25                 .paths(PathSelectors.any())
26                 .build();
27     }
28 
29     private ApiInfo buildApiInfo() {
30         Contact contact = new Contact("名字（公司或作者）","","");
31         return new ApiInfoBuilder()
32                 .title("xxxxxx-用户服务API文档")
33                 .description("包含用户服务api")
34                 .contact(contact)
35                 .version("1.0.0").build();
36     }
37 }

注意：如果是SpringBoot项目的启动类也要加@EnableSwagger2

4. Swagger常用注解

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

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

@ApiImplicitParam属性：