Swagger的基本用法

swagger是解决前后端对接问题的API框架，用它可以自动生成接口文档

• 准备工作
  使用swagger之前需要导入两个依赖
  • Springfox-swagger2
  • swagger-springmvc
  对应的依赖写法：

<dependency>
   <groupId>io.springfoxgroupId>
   <artifactId>springfox-swagger2artifactId>
   <version>2.9.2version>
dependency>

<dependency>
   <groupId>io.springfoxgroupId>
   <artifactId>springfox-swagger-uiartifactId>
   <version>2.9.2version>
dependency>

导入依赖后需要编写一个配置类

@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {  
}

当我们什么都不配置时，启动项目，打开网址
访问测试 ：http://localhost:8080/swagger-ui.html
会看到Swagger的默认界面

我们可以在配置类中自定义配置页面的各中信息，比如如下代码

1. Swagger的实例Bean是Docket，所以可以通过配置Docket配置swagger

 //配置docket以配置Swagger具体参数
@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2);
}

2. 要配置页面基本信息还需要配置一个apiInfo()属性

private ApiInfo apiInfo() {
   Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
   return new ApiInfo(
           "Swagger学习", // 标题
           "学习演示如何配置Swagger", // 描述
           "v1.0", // 版本
           "http://terms.service.url/链接", // 组织链接
           contact, // 联系人信息
           "Apach 2.0 许可", // 许可
           "许可链接", // 许可连接
           new ArrayList<>()// 扩展
  );
}

3. 将Docket与ApiInfo关联起来
   在1的代码上做一些修改

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

再次运行测试，发现页面信息已经更改为我们设置的了

完整代码

@Configuration//配置类的注解
@EnableSwagger2//开启Swagger2的自动配置
public class SwaggerConfig {

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


    private ApiInfo apiInfo(){


        Contact contact = new Contact("联系人名字","联系人的相关网址","联系人的邮箱");//作者信息
        return new ApiInfo(  "Swagger学习", // 标题
                "学习演示如何配置Swagger", // 描述
                "v1.0", // 版本
                "http://terms.service.url/组织链接", // 组织链接
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>());// 扩展)
    }
}

• 配置扫描接口
  在配置Docket时可以使用select()方法进行设置扫描接口的方式、范围
  
  这里有扫描接口的几种方式，以basePackge为例

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
    	.apis(RequestHandlerSelectors.basePackage("com.xin.swaggerdemo.controller"))
    	//.apis(RequestHandlerSelectors.basePackage("com.xin.swaggerdemo.controller"))
		//此时就设置了只扫描controller包下的接口,com.xin.swaggerdemo是我创建包的结构
      .build();
}

此时Swagger页面就只有我自己在controller包下创建的hello-controller,没有之前的basic-error-controller

• 其他配置方式的介绍：

	any() // 扫描所有，项目中的所有接口都会被扫描到
	none() // 不扫描接口
	// 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
	withMethodAnnotation(final Class<? extends Annotation> annotation)
	// 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
	withClassAnnotation(final Class<? extends Annotation> annotation)
	basePackage(final String basePackage) // 根据包路径扫描接口

另外还可以对接口名称过滤
如果设置成

就只会扫描以/xin/…形式开头的接口

定义了如下接口

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

    @RequestMapping(value = "/xin/hello")
    public String hello2(){
        return "hello xin";
    }

    @RequestMapping(value = "/hello3")
    public String hello3(){
        return "x_hello";
    }

    @RequestMapping(value = "/hello4")
    public String hello4(){
        return "hello4";
    }

最终显示的只有/xin/hello

ps:其他可选值：

any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式控制
ant(final String antPattern) // 通过ant()控制

• 配置Swagger开关

1. 开发过程中我们需要查看Swagger界面，但当项目上线后就不能给用户查看了，不然有安全隐患

 @Bean
    public Docket docket(Environment environment){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
                .enable(false)  //enable设置是否可以查看swagger页面 
                .apis(RequestHandlerSelectors.basePackage("com.xin.swaggerdemo.controller"))                
               .build();
    }

设置成false之后就无法打开swagger页面了

• 动态配置Swagger开关
  配置不同的配置文件，开发用开发的配置环境，上线用上线的配置环境
  获取当前配置环境，看是否与当前指定要显示的环境一致，根据比较结果设置boolean b的值，再，使用.enable(b)判断是否允许访问Swagger页面
  
• 设置API分组（便于团队开发）
  当前默认一个Docket，可以通过groupName（）设置名称
  可以设置多个Docket，以区分不同人设置的接口文档

@Configuration//配置类的注解
@EnableSwagger2//开启Swagger2的自动配置
public class SwaggerConfig {

    @Bean
    public Docket docket(Environment environment){

//        // 设置要显示swagger的环境
//        Profiles of = Profiles.of("dev", "test");
//        // 判断当前是否处于该环境
//        // 通过 enable() 接收此参数判断是否要显示
//        boolean b = environment.acceptsProfiles(of);//获得当前配置环境


        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
               // .groupName("BB")
                //.enable(b)
              //  .select()
             //   .apis(RequestHandlerSelectors.basePackage("com.xin.swaggerdemo.controller"))
                //此时通过 .apis(RequestHandlerSelectors.basePackage("com.xin.swaggerdemo.controller"))
                // 设置了只扫描controller包下的接口
                //.paths(PathSelectors.ant("/xin/**"))
              //  .build();
    }


    private ApiInfo apiInfo(){


        Contact contact = new Contact("联系人名字","联系人的相关网址","联系人的邮箱");//作者信息
        return new ApiInfo(  "Swagger学习", // 标题
                "学习演示如何配置Swagger", // 描述
                "v1.0", // 版本
                "http://terms.service.url/组织链接", // 组织链接
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>());// 扩展)
    }



    @Bean
    public Docket docket2(Environment environment){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("AA")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xin.swaggerdemo.controller"))
                .build();
    }

    @Bean
    public Docket docket3(Environment environment){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("CC")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xin.swaggerdemo.controller"))
                .build();
    }
//这里设置了三个docket，组名设为AA、BB、CC

此时再打开Swagger页面就会显示不同人的接口文档

• 实体配置
  当接口返回的是一个对象时，也显示在文档中，并且用注解来添加注释信息
  编写一个User实体类，写一个getUser()接口
  @ApiModel为类添加注释，可以方便查看文档的人理解
  @ApiModelProperty为类属性添加注释

package com.xin.swaggerdemo.pojo;

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

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

再写一个getUser(),返回一个User对象

  @RequestMapping( "/getUser")
    public User getUser(){
        return new User();
    }

结果就是


PS:此外，Swagger还可以用来测试接口，让我们不需要再依赖其他工具