Swagger入门

Swagger是什么

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。
简单来说，前后端开发人员联系的纽带——swagger就是一款让你更好的书写API文档的框架。

Swagger诞生背景

前后端分离

Vue + SpringBoot

后端时代：前端只用管理静态页面

• html==> 后端。模板引擎
• JSP =>后端是主力

前后端分离式时代：

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

产生一个问题：

前后端集成联调，前端人员和后端人员无法做到 “即使协商， 尽早解决”，最终导致问题集中爆发；

解决方案：

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

这时候，Swagger就出现了
Swagger的特点如下：

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

Swagger的优点

• Swagger 可以生成一个具有互动性的API控制台，开发者可以用来快速学习和尝试API。
• Swagger 可以生成客户端SDK代码用于各种不同的平台上的实现。
• Swagger 文件可以在许多不同的平台上从代码注释中自动生成。
• Swagger 有一个强大的社区，里面有许多强悍的贡献者。

Swagger的主要项目

• Swagger Codegen：通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档，同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包，docker，node等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。
• Swagger UI：提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。
• Swagger Editor:：类似于markendown编辑器的编辑Swagger描述文件的编辑器，该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。
• Swagger Inspector:：感觉和postman差不多，是一个可以对接口进行测试的在线版的postman。比在Swagger UI里面做接口请求，会返回更多的信息，也会保存你请求的实际请求参数等数据。
• Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

PS：

• Springfox Swagger：Spring 基于swagger规范，可以将基于SpringMVC和Spring Boot项目的项目代码，自动生成JSON格式的描述文件。本身不是属于Swagger官网提供的，在这里列出来做个说明，方便后面作一个使用的展开。

Swagger的使用前导

在项目使用Swagger需要springfox，包含以下两个包；

• swagger2
• ui

相关依赖如下：

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<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>

Swagger整合Spring Boot

1. 新建一个普通的SpringBoot web项目
2. 导入相关依赖
3. 编写一个名为HelloController的控制器，代码如下：

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/Hello")
public class HelloController {

    @RequestMapping("/Hello")
    public String Hello(){
        return "hello";
    }
}

4. 编写一个名为SwaggerConfig的配置文件，用于配置Swagger，代码如下：

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

5. 测试运行：http://localhost:8080/swagger-ui.html ，结果如图所示：
   

Swagger配置信息

配置相关

想要配置Swagger的信息，需要使用Docket对象，代码如下：

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2);
}

接下来，就可以使用apiconfig来配置Swagger，代码如下：

//配置Swagger信息=apiInfo
private ApiInfo apiInfo(){
    //作者信息
    Contact contact = new Contact("abc", "https://blog.csdn.net/qq_41151659", "545646733@qq.com");
    return new ApiInfo(
        "SwaggerAPI文档",
        "abc",
        "v1.0",
        "https://blog.csdn.net/qq_41151659",
        contact,
        "Apache 2.0",
        "http://www.apache.org/licenses/LICENSE-2.0",
        new ArrayList()
    );

}

若想进一步配置，则可以配置扫描接口，代码如下：

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

还可以配置是否启动Swagger，代码如下：

//配置了Swagger的Docket的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(false)//enable是否启动Swagger，如果为False，则Swagger不能再浏览器中访问
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.swagger.controller"))
                //.paths(PathSelectors.ant("/swagger/**"))
      			.build();

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

1. 判断当前是否属于生产环境，可使用flag标志位
2. 注入enable（flag）
3. 编写代码，如下所示：

//配置了Swagger的Docket的bean实例
    @Bean
    public Docket docket(Environment environment){

        //设置要显示的Swagger环境
        Profiles profiles = Profiles.of("dev","test");
        //通过environment.acceptsProfiles判断是否处在自己设定的环境当中
        boolean flag = environment.acceptsProfiles(profiles);
        System.out.println(flag);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)//enable是否启动Swagger，如果为False，则Swagger不能再浏览器中访问
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.swagger.controller"))
                //.paths(PathSelectors.ant("/swagger/**"))
                .build();
    }

设置分组

1. 设置API的分组，代码如下：

.groupName("A")

2. 要想配置多个分组，可以使用多个Socket实例，代码如下：

@Bean
public Docket docket1(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}

@Bean
public Docket docket2(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("B");
}

@Bean
public Docket docket3(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("C");
}

实体类配置

1. 编写实体类，代码如下：

package com.kuang.swagger.pojo;

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

//@Api(注释)
@ApiModel("用户实体类")
public class User {

    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;

}

2. 编写控制器，代码如下：

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

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

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

    //Operation接口,不是放在类上的，是方法
    @ApiOperation("Hello控制类")
    @GetMapping(value = "/hello2")
    public String hello2(@ApiParam("用户名") String username){
        return "hello"+username;
    }

    @ApiOperation("Post测试类")
    @PostMapping(value = "/postt")
    public User postt(@ApiParam("用户名") User user){
        int i = 5/0;
        return user;
    }
}

总结

1. 我们可以通过Swagger给一些比较难理解的属性或者接口，增加注释信息

2. 接口文档实时更新

3. 可以在线测试

4. Swagger是一个优秀的工具，几乎所有大公司都有使用它

5. 【注意点】在正式发布的时候，关闭Swagger！！！出于安全考虑。而且节省运行的内存；

Swagger详细教程

参考博客：https://blog.csdn.net/i6448038/article/details/77622977