b站狂神Swagger学习笔记

前言

前后端分离

Vue+SpringBoot

后端时代:前端只用管理静态页面;html==>后台.模板引擎JSP=>后端是主力


前后端分离时代:

• 后端:后端控制层,服务层,数据访问层
• 前端:前端控制层,视图层[前端团队]
  • 伪造后端数据,json.已经存在了,不需要后端,前端工程依旧能跑起来
• 前端后台如何交互? ==> API
• 前后端相对独立,松耦合;
• 前后端甚至可以部署在不同的服务器上;
  
  
  
  产生一个问题
• 前后端集成联调,前端人员和后端人员无法做到"即使协商,尽早解决",最终导致问题集中爆发;
  
  
  解决方案:
• 首先指定schema[计划的提纲],实时跟新最新的API,降低集成的风险;
• 早些年:指定Word计划文档;
• 前后端分离:
  • 早些年前端测试接口使用:postman工具
  • 后端提供接口,需要实时更新最新的消息及改动!

#Swagger

• 号称世界上最流行的Api框架;
• RestFul Api 文档在线自动生成工具=>Api文档与API定义同步更新
• 直接运行,可以在线测试API接口;
• 支持多种语言: java,php,等等
• Swagger官网:https://swagger.io/
  
  
  
  在项目使用Swagger需要两个jar包:
• swagger2
• ui(这里是swagger的ui界面的包)

SpringBoot集成Swagger

1.编写一个SpringBoot的web项目

2.在项目中导入Swagger相关依赖

<!-- 注意如果你用的是3.0.0版本的可能会有404的bug -->
<!-- Swagger2jar包-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!--SwaggerUi jar包-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

3.编写一个Hello工程

4.因为swagger是单独的所以需要我们进行配置

package com.example.swagger.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig extends WebMvcConfigurationSupport {

  @Override
  protected void addResourceHandlers(ResourceHandlerRegistry registry) {
    // 解决静态资源无法访问
    registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
    // 解决swagger无法访问
    registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
    // 解决swagger的js文件无法访问
    registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
  }
}

因为Swagger是一个单独的包并没有被整合!

5.进行测试访问http://localhost:8080/swagger-ui.html

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-KNQQtw5D-1655267560365)(img.png)]

配置Swagger配置

package com.example.swagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig extends WebMvcConfigurationSupport{

    //Docket是Swagger自己的实例需要我们自己放入SpringBoot容器中!
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()); //配置Swagger的bean实例
    }

    //配置Swagger信息(ApiInfo)
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact=new Contact("小步","https://tang.aistudynet.com.cn/","3068384097@qq.com");

        return new ApiInfo("小步的接口文档" //标题
                , "这个作者有点酷" //描述
                , "1.0" //版本
                , "https://tang.aistudynet.com.cn/"
                ,  contact
                , "Apache 2.0"
                , "https://swagger.io/"
                ,  new ArrayList<>());
    }

    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 解决静态资源无法访问
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        // 解决swagger无法访问
        registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        // 解决swagger的js文件无法访问
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

配置扫描接口与过滤

接口扫描:

• Docket.select()

    @Bean
    public Docket docket(){
        //配置Swagger的bean实例
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //配置要扫描接口的方式
                .select()
                //RequestHandlerSelectors 配置接口要扫描的方式
                //basePackage("com.example.swagger.controller") 指定要扫描的包
                //any() 扫描全部
                //none() 不扫描
                //withClassAnnotation()或withMethodAnnotation() 扫描类|方法上的注解，传入扫描注解的class对象
                .apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
                .build();
    }

过滤:

• paths() 过滤

    //Docket是Swagger自己的实例需要我们自己放入SpringBoot容器中!
    @Bean
    public Docket docket(){
        //配置Swagger的bean实例
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //配置要扫描接口的方式
                .select()
                //RequestHandlerSelectors 配置接口要扫描的方式
                //basePackage("com.example.swagger.controller") 指定要扫描的包
                //any() 扫描全部
                //none() 不扫描
                //withClassAnnotation()或withMethodAnnotation() 扫描类|方法上的注解，传入扫描注解的class对象
                .apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
                //paths()过滤  PathSelectors路径选择器
                .paths(PathSelectors.none())
                .build();
    }

关闭Swagger

• enable(false)

.enable(false) //关闭Swagger

小练习:我只希望在生产环境中使用,不希望在正式环境中使用

• 判断是不是生产环境
• 注入enable()

//Docket是Swagger自己的实例需要我们自己放入SpringBoot容器中!
    @Bean
    public Docket docket(Environment environment){
        //进行控制权限,表示只有在test环境下才开启swaggerConfig
        Profiles test = Profiles.of("test");
        //返回当前是否为test环境
        boolean flag = environment.acceptsProfiles(test);

        //配置Swagger的bean实例
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag) //关闭Swagger
                //配置要扫描接口的方式
                .select()
                //RequestHandlerSelectors 配置接口要扫描的方式
                //basePackage("com.example.swagger.controller") 指定要扫描的包
                //any() 扫描全部
                //none() 不扫描
                //withClassAnnotation()或withMethodAnnotation() 扫描类|方法上的注解，传入扫描注解的class对象
                .apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
                //paths()过滤  PathSelectors路径选择器
                .paths(PathSelectors.none())
                .build();
    }

Swagger分组

    @Bean
    public Docket docket02(){
        //再次设置一个组
        return new Docket(DocumentationType.SWAGGER_2).groupName("docket02");
    }

    @Bean
    public Docket docket03(){
        //再次设置一个组
        return new Docket(DocumentationType.SWAGGER_2).groupName("docket03");
    }

Swagger注释

package com.example.swagger.pojo;

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

@ApiModel("用户实体类")
public class User {

    @ApiModelProperty("用户id")
    private Integer id;
}

同时也还有许多注释这里不在一一叙述