Swagger的配置与使用

问题：前后端分离时代的到来

• 前端需要测试后端数据

• 后端提供接口，实时更新接口的改动

一、Swagger简介

• 号称世界上最流行的api框架

• Restful api文档在线自动生成工具–>api文档与api定义同步更新

• 直接运行，可以在线测试api接口

• 支持多种语言(java、php)

官网：https://swagger.io/

在项目中使用swagger需要springfox jar包

• swagger2
• swagger ui

二、springboot集成swagger

1. 新建springboot项目

2. 导入jar包

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

3. 编写一个helloworld

   package com.kj.controller;
   
   import org.springframework.web.bind.annotation.RequestMapping;
   import org.springframework.web.bind.annotation.RestController;
   
   @RestController
   public class SwaggerController {
   
       @RequestMapping("/hello")
       public String hello(){
           return "hello";
       }
   }
   

4. 配置swagger

   import org.springframework.context.annotation.Configuration;
   import springfox.documentation.swagger2.annotations.EnableSwagger2;
   
   @Configuration
   @EnableSwagger2 //开启swagger
   public class SwaggerConfig {
   
   }
   

   启动类加上@EnableSwagger2注解（遇到Unable to infer base url.bug时加入，可以解决）

   package com.kj;
   
   import org.springframework.boot.SpringApplication;
   import org.springframework.boot.autoconfigure.SpringBootApplication;
   import springfox.documentation.swagger2.annotations.EnableSwagger2;
   
   @SpringBootApplication
   @EnableSwagger2
   public class SwaggerDemoApplication {
   
       public static void main(String[] args) {
           SpringApplication.run(SwaggerDemoApplication.class, args);
       }
   
   }
   

5. 启动运行

   访问localhost/swagger-ui.html。没有配置port的是这个地址localhost:8080/swagger-ui.html

   swagger-ui.html所在文件
   
   

三、配置swagger

1、配置ApiInfo

swagger需要一个docket实例

可以看到docket的构造函数，需要一个DocumentationType

public Docket(DocumentationType documentationType) {
    this.apiInfo = ApiInfo.DEFAULT;
    this.groupName = "default";
    this.enabled = true;
    this.genericsNamingStrategy = new DefaultGenericTypeNamingStrategy();
    this.applyDefaultResponseMessages = true;
    this.host = "";
    this.pathMapping = Optional.absent();
    this.apiSelector = ApiSelector.DEFAULT;
    this.enableUrlTemplating = false;
    this.vendorExtensions = Lists.newArrayList();
    this.documentationType = documentationType;
}

而DocumentationType有三个默认的值

public class DocumentationType extends SimplePluginMetadata {
    public static final DocumentationType SWAGGER_12 = new DocumentationType("swagger", "1.2");
    public static final DocumentationType SWAGGER_2 = new DocumentationType("swagger", "2.0");
    public static final DocumentationType SPRING_WEB = new DocumentationType("spring-web", "1.0");
    
......
    
}

所以我们可以这样向容器中创建一个docket

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2);
}

此时改配置信息，调用docket的函数即可。

比如修改swagger的api信息，我们需要更改ApiInfo

相关源码

public Docket(DocumentationType documentationType) {
    this.apiInfo = ApiInfo.DEFAULT; //api描述
    this.groupName = "default";
    this.enabled = true;
    this.genericsNamingStrategy = new DefaultGenericTypeNamingStrategy();
    this.applyDefaultResponseMessages = true;
    this.host = "";
    this.pathMapping = Optional.absent();
    this.apiSelector = ApiSelector.DEFAULT;
    this.enableUrlTemplating = false;
    this.vendorExtensions = Lists.newArrayList();
    this.documentationType = documentationType;
}

//默认的apiInfo
static {
    DEFAULT = new ApiInfo("Api Documentation",
                          "Api Documentation",
                          "1.0", "urn:tos",
                          DEFAULT_CONTACT,
                          "Apache 2.0",
                          "http://www.apache.org/licenses/LICENSE-2.0",
                          new ArrayList());
}

//作者信息
public static final Contact DEFAULT_CONTACT = new Contact("", "", "");

这时候为我们自己的docket注入咱们自己的apiInfo即可

@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo());
}

private static ApiInfo getApiInfo(){
return new ApiInfo("KJ Api文件",
"swagger测试",
"1.0",
"https://blog.csdn.net/KJ_Study",
new Contact("KJ", "https://blog.csdn.net/KJ_Study", "qi1638629056@163.com"),
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}

结果如下（其实这个基本没任何效率上的作用）

2、配置扫描接口

有一个方法Docket.select()

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo())
            .select()
            .build();
}

只能build两个方法apis与paths

配置扫描目标

有扫描全部any，一个都不扫描none，基于包扫描basePackage，通过方法注解扫描（扫描有这个注解的方法，可以自己加入GetMapper.class的参数），通过类注解扫描

用的多的还是basePackage

我们指定一个扫描包

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo())
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.kj.controller")) //RequestHandlerSelectors配置扫描接口的方式
        .build();
}

结果

3、过滤路径

扫描带有/kj/ url的api，我们只有一个/hello请求，所以不会有任何api

@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo())
    .select()
    .apis(RequestHandlerSelectors.basePackage("com.kj.controller"))
    .paths(PathSelectors.ant("/kj/**"))
    .build();
}

4、配置是否启用swagger

将docket的enabled属性改为false即可

//docket的部分源码
public Docket(DocumentationType documentationType) {
    this.apiInfo = ApiInfo.DEFAULT;
    this.groupName = "default";
    this.enabled = true; //是否使用swagger
    this.genericsNamingStrategy = new DefaultGenericTypeNamingStrategy();
    this.applyDefaultResponseMessages = true;
    this.host = "";
    this.pathMapping = Optional.absent();
    this.apiSelector = ApiSelector.DEFAULT;
    this.enableUrlTemplating = false;
    this.vendorExtensions = Lists.newArrayList();
    this.documentationType = documentationType;
}

public Docket enable(boolean externallyConfiguredFlag) {
    this.enabled = externallyConfiguredFlag;
    return this;
}

所以我们enable一下

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.kj.controller")) //RequestHandlerSelectors配置扫描接口的方式
            .build()
            .enable(false);
}

实际使用：我们通过外部的环境来判断是否调用swagger

@Bean
public Docket docket(Environment environment){
    //设置显示要调用swagger的环境，可以有多个值
    Profiles profiles = Profiles.of("dev");
    //判断当前的环境与指定的是否一样
    boolean flag = environment.acceptsProfiles(profiles);

    return new Docket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.kj.controller")) //RequestHandlerSelectors配置扫描接口的方式
            .build()
            .enable(flag);
}

我们有多个配置文件，一个用于开发，一个用于部署

5、配置api文档的分组

主要的是groupName

public Docket(DocumentationType documentationType) {
    this.apiInfo = ApiInfo.DEFAULT;
    this.groupName = "default";
    this.enabled = true;
    this.genericsNamingStrategy = new DefaultGenericTypeNamingStrategy();
    this.applyDefaultResponseMessages = true;
    this.host = "";
    this.pathMapping = Optional.absent();
    this.apiSelector = ApiSelector.DEFAULT;
    this.enableUrlTemplating = false;
    this.vendorExtensions = Lists.newArrayList();
    this.documentationType = documentationType;
}

@Bean
public Docket docket(Environment environment){
    Profiles profiles = Profiles.of("dev");
    boolean flag = environment.acceptsProfiles(profiles);

    return new Docket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.kj.controller"))
            .build()
            .enable(flag)
            .groupName("KJ");
}

我们可以看到一个docket一个分组。要想要多个我们再创建几个docket即可。

注意组名不能相同，如果相同spring会报bug并结束进程

@Bean
public Docket docket1() {
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo())
        .groupName("A");
}

@Bean
public Docket docket2() {
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo())
        .groupName("B");
}

@Bean
public Docket docket3() {
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo())
        .groupName("C");
}

不同后端开发人员选择自己的组，就可以只看到自己的api

6、实体类配置

只要返回值中存在，就会被swagger扫描

编写一个pojo

package com.kj.pojo;

public class User {
    private String username;
    private String password;
}

编写一个方法

@RestController
public class SwaggerController {

    @RequestMapping("/hello")
    public String hello(){
        return "hello";
    }

    @PostMapping("/user")
    public User user(){
        return new User();
    }
}

我们也可以在实体类加上注注释（在显示时，只显示注解配置的内容），显不显示与这个注解无关

package com.kj.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("实体类")
public class User {
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    private String password;
}

可以看到私有方法是看不到的

同样我们也可以给方法加注释，或者给参数加注释

@RestController
public class SwaggerController {

    @ApiOperation("哈喽方法")
    @RequestMapping("/hello")
    public String hello(){
        return "hello";
    }

    @PostMapping("/user")
    public User user(){
        return new User();
    }
    
    @GetMapping("/hello2")
    public String hello2(@ApiParam("用户名") String name){
        return "hello";
    }
}

四、发送请求

下面就可以看到结果了