Swagger

官网：https://swagger.io/

一、作用：

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

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

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

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

import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@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.xxx.xxxxxx"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo buildApiInfo() {
        Contact contact = new Contact("名字（公司或作者）","","");
        return new ApiInfoBuilder()
                .title("xxxxxx-用户服务API文档")
                .description("包含用户服务api")
                .contact(contact)
                .version("1.0.0").build();
    }
}

注意：如果是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属性：