springboot04-Swagger

Swagger

学习目标：

• 了解Swagger的作用和概念
• 了解前后端分离
• 在SpringBoot中集成Swagger

swagger简介

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

• RestFul API文档在线自动生成工具=》API文档与Api定义同步更新

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

官网：https://swagger.io

在项目使用Swagger需要springfox

swagger2

ui

SpringBoot集成Swagger

• 新建一个springBoot——web项目

• 导入相关依赖

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

• 编写一个Hello工程

• 配置Swagger------->Config

  @Configuration
  @EnableSwagger2WebMvc  //开启Swagger2
  public class SwaggerConfig {
  }
  
  

• 测试运行 http://localhost:8080/swagger-ui.html

配置swagger

Swagger的bean实例Docker

//配置了swagger的Docket的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
               
    }

    //配置swagger信息的ApiInfo
    private ApiInfo apiInfo() {
       Contact contact = new Contact("林森", "https://www.cnblogs.com/mjjh/", "1962521583@qq.com");
        return new ApiInfo(
                "Api Documentation",
                "Api Documentation",
                "1.0",
                "urn:tos",
                contact, "Apache 2.0",
                "https://www.cnblogs.com/mjjh/",
                new ArrayList<VendorExtension>());

    }

配置扫描接口

 public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)      
           .apiInfo(apiInfo())
                .select()
                 /**
         *RequestHandlerSelectors配置要扫描接口的方式
         basePackage指定扫描包   最常用的
         any()扫描全部
         none()扫描都不扫描
         withClassAnnotation(RestController.class)扫描类上的注解，参数是一个注解的反射对象
         withMethodAnnotation(GetMapping.class)扫描方法上的注解
         */
                .apis(RequestHandlerSelectors.basePackage("com.mjh.controller"))
               //paths（）过滤扫什么路径
                .paths(PathSelectors.ant("/mjh/**"))
                .build();
    }

配置是否启动Swagger

@Bean
      public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(false)  //是否启动Swagger，如果为false，则Swagger不能再浏览器中使用
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.mjh.controller"))
                .build();
    }

只希望我的Swagger在生产环境中使用，在发布的时候不使用?

• 判断是不是生产环境 flag=false

• 注入enable（flag）

  application.properties
      spring.profiles.active=dev
  

  application-dev.yml
      server:
    port: 8081
  

  application-pro.yml
      server:
    port: 8082
  

  //配置了swagger的Docket的bean实例
      @Bean
        public Docket docket(Environment environment){
          //设置要显示的Swagger环境
          Profiles profiles=Profiles.of("dev","test");//这里可以配置多个
          //通过environment.acceptsProfiles()判断是否在自己设定的环境当中
          boolean flag = environment.acceptsProfiles(profiles);
  
          return new Docket(DocumentationType.SWAGGER_2)
                  .apiInfo(apiInfo())
                  .enable(flag)
                  .select()
                  .apis(RequestHandlerSelectors.basePackage("com.mjh.controller"))
                  .build();
      }
  
  

  配置Api文档的分组

  .groupName("日志")
  

如何配置对个分组（多个Docket实例即可）

@Bean
public Docket docket1(Environment environment){

    return new Docket(DocumentationType.SWAGGER_2).groupName("笔记");
}
@Bean
public Docket docket2(Environment environment){
    return new Docket(DocumentationType.SWAGGER_2).groupName("随笔");
}
@Bean
public Docket docket3(Environment environment){
    return new Docket(DocumentationType.SWAGGER_2).groupName("首页");
}

实体类配置

注释就是为了给swagger说明

//@Api(注释)等价于
@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    public String name;
    @ApiModelProperty("电话")
    public String phone;
}

@RestController
public class HelloController {
    @GetMapping("/hello")
    public String hello(){
        return "helloo";
    }

    /**
     * 只要我们的接口中，返回值中存在实体类，就会被扫描到Swagger中
     * @return
     */
    @PostMapping("/user")
    public User user(){
        return new User();
    }

    //ApiOperation接口  放在方法上
    @ApiOperation("Hello控制类")
    @PostMapping("/hello1")
    public String hello1(@ApiParam("用户名") String name){
        return "Hello"+name;
    }
}

• 我们可以通过Swagger给一些比较难理解的属性或者接口，增加注释信息
• 接口文档实时更新
• 可以在线测试

注意：出于安全考虑，在正式发布的时候要关闭Swagger