12、Swagger详解

1、使用Swagger的功能首先引入Swagger的依赖

<!-- Swagger相关的依赖开始 -->
<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>
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-models</artifactId>
    <version>1.6.0</version>
</dependency>
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>1.6.0</version>
</dependency>
<!-- Swagger相关的依赖结束 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-configuration-processor</artifactId>
    <optional>true</optional>
</dependency>

2、编写Swagger的核心配置

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Autowired
    private MyApiPojo myApiPojo;

　　//是否开启Swagger
　　@Value("${swagger.enable}")
　　private boolean enableSwagger;

    @Bean
    public Docket createRestApiA() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("分组二");
    }

    @Bean
    public Docket createRestApiB() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("分组三");
    }

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("分组一")
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.kuang.controller"))
                .paths(PathSelectors.any())
                .build().apiInfo(getApiInfo());
    }


    public ApiInfo getApiInfo () {
        Contact contact = new Contact("危存盛", "http://www.baidu.com", "16352900773@qq.com");
        return new ApiInfo(
                myApiPojo.getTitle(),
                myApiPojo.getDescription(),
                myApiPojo.getVersion(),
                myApiPojo.getTermsOfServiceUrl(),
                contact,
                myApiPojo.getLicense(),
                myApiPojo.getLicenseUrl(),
                new ArrayList<>());
    }
}

3、使用Spring的配置文件去绑定一个实体类

@Component
@ConfigurationProperties(prefix = "my-swagger")
public class MyApiPojo {

    private String title;
    private String description;
    private String version;
    private String termsOfServiceUrl;
    private String license;
    private String licenseUrl;
}

4、编写主配置文件application.yml

my-swagger:
  title: Swagger2的在线生成API文档
  description: 欢迎来到这里
  version: v1.0.0
  termsOfServiceUrl: 欢迎来到这里
  license: The Apache License
  licenseUrl: http://www.baidu.com

swagger:
  enable: true

 5、controller测试，加上swagger的注解，自动生成APi文档的描述

@Api(tags = "我的测试Swgger")
@RestController
public class HelloController {

    @ApiOperation(value = "我的hello方法")
    @GetMapping("/hello")
    public String hello() {
        return "hello";
    }

    @ApiOperation(value = "我的hello2方法")
    @GetMapping("/hello2")
    public UserTest hello2(UserTest userTest) {
        return userTest;
    }

    @ApiOperation(value = "我的hello3方法")
    @GetMapping("/hello3")
    public UserTest hello3(@RequestBody UserTest userTest) {
        return userTest;
    }
}

6、实体类上的Swagger注解

@ApiModel(value = "我的实体类")
public class UserTest {

    @ApiModelProperty(value = "姓名")
    private String name;
    @ApiModelProperty(value = "年龄")
    private String age;
}

7、经常使用到的Swagger注解有：

@ApiImplicitParam：一个普通参数上的注解，描述这个字段用来干嘛的

@ApiImplicitParam：多个普通参数上的注解，描述这个字段用来干嘛的

@Api：b标注在Controller类上，描述这个接口的功能

@ApiOperation：标注在Controller的方法上，描述这个方法的功能

@ApiModel： 标注在实体类类上，描述这个类的功能

@ ApiModelProperty：标注在实体类类上，描述这个类下的字段描述