springBoot笔记（八）---swagger进行API管理

Swagger

什么是前后端分离？

​ Vue + springBoot

​ 前后端会有联调问题出现，需要实现及时更新API；

swagger定义：Resful API 文档在线自动生成工具------>API文档和API接口同步更新

1.在项目中使用Swagger：（springboot集成）

• 导入依赖包：springbfox

  • swagger2

  • ui

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

• Swagger配置：

  • config配置文件,定制swagger-ui页面的部分信息：Docket

  • 配置扫描哪些接口及是否开启swagger

    @configuration
    @EnableSwagger2
    public class SwaggerConfig{
        @Bean
        public Docket docket(){
            return new Docket(DocumentationType.SWAGGER_2)
                       .apiInfo(apiInfo())
                       //.enable(false/true)   // 是否开启swagger
                       .select()
                        // RequestHandlerSelectors 表示配置要扫描接口的方式
                        // basepackage:指定要扫描的包，使用的最多
                        // ang():扫描全部
                        // none():不扫描
                        // 还有就是扫描类或是方法上的注解的class
                       .apis(RequestHandlerSelectors.XXX());  //XXX表示扫描方法
                       .paths(PathSelectors.XXX()) // PathSelectors.XXX()表示过滤的路径方式
                       .build();
        }
        //apiInfo()方法重写
        private ApiInfo apiInfo(){
            // 作者信息
            Contact contact = new Contact("zhang","http://zhangblog.com","123456@qq.com");
            return new ApiInfo(title:...);    // ui中的版本之类的信息，可以自己写
        }
        
    }
    

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

• 如何在生产环境中不使用swagger，在测试环境使用swagger？

  1.判断是当前处于什么环境

  2.通过判断环境，决定swagger是否开启

  // 就是上面的Docket方法，传递一个环境参数 
  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)   // 根据flag就可以决定是否开启swagger
  }
  

• swagger分组：使用.groupName(“组名”)

  进行多个分组就创建多个Docket实例，并放入@Bean

• 创建的实例类如何被swagger扫描到？

  在controller方法中如果返回值有实例类就会被swagger扫描到；

• 几个注解

  // 创建一个类用于演示，下面的几个注释会在swagger-ui中生成中文的注释，方便别人理解代码
  @ApiModel("用户实体类")                     
  public class User{
      
      @ApiModelProperty("用户名")
      private String username;
      
      @ApiModelProperty("用户密码")
      private String password;
  }
  

  @ApiOperation("") 接口注释

​ @ApiParam(“”) 给参数加注释

2.swagger可以在ui界面直接对方法和类进行测试；