Swagger的使用（整合SpringBoot）

Swagger的使用（SpringBoot）

简介

前后端分离

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

前后端分离时代：

• 后端：后端控制层、服务层、数据库访问层

• 前端：前端控制层、视图层

  • 伪后端数据，json。（不需要后端，前端也可以跑起来）

• 前后端交互：通过api

• 前后端相互独立，松耦合

• 前后端可以部署在不同的服务器

• 问题：

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

• 解决方法：

  • 首先制定计划，实时更新最新api，降低集成风险
  • 早些年使用word计划文档
  • 前后端分离时代可以使用：前端测试后端接口：postman

swagger

• 号称世界上最流行的API框架
• RestFul Api文档在线自动生成工具–>api文档和api定义同步更新
• 直接运行，可以在线测试Api接口
• 支持多种语言：java、php等等

官网：https://swagger.io/

在项目中使用

引入依赖

新建SpringBoot项目,引入Swagger相关依赖：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.qianyu</groupId>
    <artifactId>demo</artifactId>
    <version>1.0-SNAPSHOT</version>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.1.6.RELEASE</version>
        <relativePath/>
    </parent>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <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>
    </dependencies>
</project>

新建HelloWorld

• controller

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

• 主类

@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

• application.yml

server:
  port: 9000

• Swagger配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket getDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    // 配置Swagger的ApiInfo
    private ApiInfo apiInfo() {
        // 作者信息
        Contact contact = new Contact("芊雨", "http://www.qianyucc.xyz/", "1413979079@qq.com");
        return new ApiInfo(
                "芊雨的博客API文档",
                "博客后端所有的api接口",
                "v1.0.0",
                "http://localhost:8886/",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

运行项目，在浏览器访问http://localhost:9000/swagger-ui.html，即可看到api文档：

配置包扫描和只在开发环境生效

• 新建application-dev.yml和application-pro.yml分别表示开发环境和生产环境
• 在application.yml中启用开发环境

server:
  port: 9000
spring:
  profiles:
    active: dev

• 修改配置类

@Bean
public Docket getDocket(Environment environment) {
    // 如果在dev环境（开发环境）就开启Swagger
    boolean isDev = environment.acceptsProfiles(Profiles.of("dev"));
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .enable(isDev)
            .select()
            // 配置需要扫描的包
            .apis(RequestHandlerSelectors.basePackage("com.qianyu.demo.controller"))
            // 配置需要匹配的路径
            //.paths(PathSelectors.ant("/api/**"))
            .build();
}

这时候只有在开发环境中访问http://localhost:9000/swagger-ui.html才能看到文档内容

分组功能的实现

在Swagger配置类中，我们可以只用多个Docket对象来完成分组，因为在开发过程中每个人可能负责一个模块，所以每个人都可以配置一个属于自己的Docket，并且在里面实现个性化配置

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

@Bean
public Docket docke2() {
    return new Docket(DocumentationType.SWAGGER_2).groupName("李四");
}

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

文档注释

默认情况下，只要接口的返回值中存在实体类，就会被扫描到Swagger中

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

如图所示：

我们也可以使用注解来书写注释

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

@ApiOperation("查询用户名是否存在")
@GetMapping("/demo")
public String demo(@ApiParam("用户名") String username) {
    return "res:" + username;
}

此时，在文档上就会出现我们自定义的注释：