Swagger 入门

5 Swagger介绍以及集成

目录

1 Swagger 简介与搭建环境

2 配置Swagger 信息

3 配置扫描接口以及开关

4 分组和接口注释以及小结

1 Swagger 简介

1 由来

前后端分离时代

1 **后端为主的时代，**前端只需要写静态页面，后台要写模板，通过模板引擎加载渲染数据，前端需要通过后端传递数据项目才能运行起

2 前后端分离

• 后端： 后端控制层，服务层，数据访问层 【后端】
• 前端，视图层，前端控制层，
  • 伪造后端JSON数据，不需要后端，前端的工程也能运行，
• 前后端交互，通过API
• 前端后独立-松耦合

问题

• 前后端集成联调，前端和后端人员无法做到即使协商

解决

• 指定 schema 计划提纲，实时更新最新的API降低集成的风险
• 早些年，通过Word计划文档，+GIT

2 搭建Swagger 环境

1 编写一个SpringBoot 的HelloWorld程序

2 导入Swagger依赖 注意3.0 版本有较大改动，这里为2.9 版本

 <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

3 编写一个配置类-SwaggerConfig来配置 Swagger

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

4 访问测试 ：http://localhost:8080/swagger-ui.html ，可以看到swagger的界面；

2 配置Swagger 的信息

1 Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger。

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

2、可以通过apiInfo()属性配置文档信息

 @Bean
    public Docket getDocket1(){
               return  new Docket(DocumentationType.SWAGGER_2)
                .groupName("A")
                .apiInfo(apiInfo())
                ;
    }
    	
       @
       public ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("jian", "www.baidu.com", "1222434@qq.com");
        return  new ApiInfo("狂神的swagger", "配置Swagger的信息", "1.0", "urn:tos",
                contact, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList<VendorExtension>());
    }
   

这里还可以使用ApiInfoBuilder().build来初始化apiInfo

public ApiInfo apiInfo(){
        return  new ApiInfoBuilder().title("老罗的Swagger")
                .version("初始版本 1.0")
                .contact(new Contact("老罗","www.baidu.com","cup_1sdf2078935@163.com"))
                .description("springboot swagger 学习").build();
    }

3 访问测试 http://localhost:8080/swagger-ui.html

3 配置扫描接口以及开关

1 构建Docket时通过select()方法配置怎么扫描接口。

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.swagger.controller"))
      .build();
}

.select() 返回的是一个 ApiSelectorBuilder 对象

ApiSelectorBuilder 有三个方法

• build() //返回一个Docket实例
• apis() //配置要扫描的接口
• paths() //配置扫描过滤

 public Docket build()   //返回一个Docket实例
 
  public ApiSelectorBuilder paths(Predicate<String> selector) //配置扫描过滤
   public ApiSelectorBuilder apis(Predicate<RequestHandler> selector) //配置要扫描的接口

通常配置要扫描的接口，可以通过RequestHandlerSelectors的静态方法

 public static Predicate<RequestHandler> any() // 扫描所有接口
 
 public static Predicate<RequestHandler> none() // 不扫描接口
 
 public static Predicate<RequestHandler> withMethodAnnotation // public static Predicate<RequestHandler> withMethodAnnotation //扫描方法上Xxx注释的接口
 
 public static Predicate<RequestHandler> withClassAnnotation //扫描类上有Xxx注释的接口
 
  public static Predicate<RequestHandler> basePackage//扫描哪些包

通常配置要过滤的接口，可以通过类PathSelectors的静态方法

//过滤所有的
public static Predicate<String> any() {
        return Predicates.alwaysTrue();
    }
//什么都不过滤
    public static Predicate<String> none() {
        return Predicates.alwaysFalse();
    }
//过滤符合正则表达式的路径
    public static Predicate<String> regex(final String pathRegex) {
        return new Predicate<String>() {
            public boolean apply(String input) {
                return input.matches(pathRegex);
            }
        };
    }
//过滤指定的路径
    public static Predicate<String> ant(final String antPattern) {
        return new Predicate<String>() {
            public boolean apply(String input) {
                AntPathMatcher matcher = new AntPathMatcher();
                return matcher.match(antPattern, input);
            }
        };
    }

例子

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
       // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
      .paths(PathSelectors.ant("/swagger/**"))
      .build();
}

---

2 配置开关

1、通过enable()方法配置是否启用swagger，如果是false，swagger将不能在浏览器中访问了

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .enable(false) //配置是否启用Swagger，如果是false，在浏览器将无法访问
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
       // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
      .paths(PathSelectors.ant("/kuang/**"))
      .build();
}

2 问题如何配置当项目处于test、dev环境时显示swagger，处于prod时不显示？

• 检查test、dev环境 是否激活，激活则为true

@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())
      .enable(b) //配置是否启用Swagger，如果是false，在浏览器将无法访问
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
       // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
      .paths(PathSelectors.ant("/kuang/**"))
      .build();
}

• Profiles.of(“dev”, “test”); 获取要检测 的环境
• environment.acceptsProfiles(of); 判断环境是否激活

设置多文档环境

server:
  port: 8080
spring:
  profiles:
    active: prod

---
spring:
  profiles: dev

server:
  port: 8081

---
spring:
  profiles: prod

server:
  port: 8082

3 测试，成功

4 分组和接口注释以及小结

1 如果没有配置分组，默认是default。通过groupName()方法即可配置分组：

@Bean
public Docket docket(Environment environment) {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
      .groupName("hello") // 配置分组
       // 省略配置....
}

2 重启项目查看分组

3、如何配置多个分组？配置多个分组只需要配置多个docket即可：

@Bean
public Docket docket1(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}

结果

Model 测试

可以发现Model 并没有内容，

1 建立一个实体类

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

2 只要这个实体在请求接口的返回值上（即使是泛型），都能映射到Model项中：

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

并不是因为@ApiModel这个注解让实体显示在这里了，而是只要出现在接口方法的返回值上的实体都会显示在这里，而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的。

@ApiModel为类添加注释

@ApiModelProperty为类属性添加注释

3 接口注释

Swagger的所有注解定义在io.swagger.annotations包下

下面列一些经常用到的，未列举出来的可以另行查阅说明：

• 描述方法的注解
• @ApiOperation(value = “请求swagger方法”,notes =“这是一个hello方法”)
• 描述参数的注解
• 单个参数
• @ApiImplicitParam 作用在方法上，描述一个参数
• 多个参数
• @ApiImplicitParams({
  @ApiImplicitParam(name = “username”,value = “用户名”),
  @ApiImplicitParam(name = “pwd”,value = “密码”)
  })

这样的话，可以给一些比较难理解的属性或者接口，增加一些配置信息，让人更容易阅读！

，提醒下大家在正式环境要记得关闭Swagger，一来出于安全考虑二来也可以节省运行时内存。

@RequestParam：将请求参数绑定到你控制器的方法参数上（是springmvc中接收普通参数的注解）

总结

Swagger 的使用步骤

• 1 导入swagger依赖
• 2 配置Swagger
  • 1 配置Docket
  • 2 配置apiInfo
• 3 在扫描的接口上配置注释信息