快速了解Swagger及其快速入门

Swagger

学习目标：

• 了解swagger的作用和概念
• 了解前后端分离
• 在spring boot集成swagger

swagger简介

前后端分离

vue+Springboot

后端时代：前端只用管静态页面；html==》后端；模板引擎jsp==》后端是主力

前后端分离时代：

• 后端：后端控制层，服务层，数据访问层【后端团队】
• 前端：前端控制层，视图层【前端工程】
  • 伪后端数据，json，已经存在了，不需要后端，前端功能也能跑起来
• 前后端如何交互？==>API
• 前后端相对独立，松耦合；
• 前后端甚至可以部署在不同的服务器中运行

产生一个问题：

• 前后端集成联调：前端人员和后端人员无法做到“及时沟通，尽早解决”。最终导致问题集中爆发。

解决方案：

• 首先指定一个schema【计划提纲】，然后实时更新最新API，降低集成风险。
• 早些年，制定word计划文档；
• 前后端分离：
  • 前端测试后端接口：postman
  • 后端提供接口，需要实时更新最新的消息及改动。

Swagger

• 号称世界上最流行的API框架；
• Restful APi 文档在线自动生成工具==>APi文档与API定义同步更新
• 直接运行，可以在线测试API接口；
• 支持各种语言：php，Java…

官网：API Documentation & Design Tools for Teams | Swagger

在项目中swagger需要springfox；

• swagger2
• ui

spring boot集成swagger

1. 新建一个spring boot-web项目

2. 导入相关依赖

   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger2</artifactId>
       <version>2.9.2</version>
   </dependency>
   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger-ui</artifactId>
       <version>2.9.2</version>
   </dependency>
   

3. 编写一个hello工程

4. 配置swaggerconfig

   @Configuration
   @EnableSwagger2//开启swagger2
   public class SwaggerConfig {
   }
   

5. 直接运行http://localhost:8080/swagger-ui.html

swagger配置

@Configuration
@EnableSwagger2//开启swagger2
public class SwaggerConfig {

    //配置swagger的Docket的bean示例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }
    //配置swagger信息apiInfo()
    private ApiInfo apiInfo(){
        Contact contact = new Contact("", "", "");
        return new ApiInfo(
                "彬彬的swagger",
                "Api Documentation",
                "1.0", "urn:tos",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

遇见了问题：但我发现spring boot2.6和swagger不兼容，怎样去解决？

解决方法：(8条消息) springboot学习(六十一) 解决springboot2.6和swagger冲突的问题_文若书生的专栏-CSDN博客

Swagger配置扫描接口

 @Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .select()
        //RequestHandlerSelectors：配置扫描接口的方式
        //basePackage:指定扫描的包,一般用这个
        //any():扫描全部
        //none():都不扫描
        //withClassAnnotation():扫描类上的注解,参数是一个注解的反射对象
        //withMethodAnnotation:扫描类上的注解
        .apis(RequestHandlerSelectors.basePackage("com.zyb.swaggerweb.controller"))
        //paths():过滤什么路径
        .paths(PathSelectors.ant("/zyb/**"))
        .build();
}

配置是否启动swagger

题目：我只希望swagger中在生产环境中使用，在发布的时候不用？

• 判断环境是否为生产环境（flag）
• 注入Enable（flag）

@Bean
public Docket docket(Environment environment){
    //设置swagger要显示的环境
    Profiles profiles = Profiles.of("dev");
    //通过environment.acceptsProfiles来监听是否处在自己设置的环境中
    boolean flag = environment.acceptsProfiles(profiles);

    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .enable(flag)
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.zyb.swaggerweb.controller"))
        .build();
}

配置APi分组

groupName("李四")

如何配置多个分组，多个Docket示例

@Bean
public Docket docket1(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("张三");
}
@Bean
public Docket docket2(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("李四");
}
@Bean
public Docket docket3(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("王五");
}

实体类

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

控制器

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

    @PostMapping(value = "/user")
    public User user(){
        return new User();
    }

    @GetMapping(value = "/hell2")
    public String heloo(@ApiParam("用户名") String username){
        return "hello"+username;
    }

}

总结：

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

【注意点】在正式发布的时候，关闭swagger！！处于安全考虑，而且节省内存