Swagger学习笔记

教程地址：https://www.bilibili.com/video/BV1Y441197Lw

Swagger简介

现在的项目通常是前后端分离的，前端和后端的数据交互通过API进行，前后端松耦合。这时候就需要有一个东西，可以解决API随时变动的问题，当后端修改了API接口，前端可以及时了解到，避免沟通不及时产生问题。Swagger就是这么一个工具。
使用了Swagger，可以在线生成文档和测试接口，API文档和API定义同步更新，减轻了维护的成本。
Swagger的官网。

Swagger和Spring的集成

使用IDEA新建一个Spring的项目。选中“Spring Web”模块，在pom.xml里添加Swagger的相关依赖。

<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>

编写HelloController.java测试类。

package com.demo.swagger.controller;

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

@RestController
public class HelloController {
    @RequestMapping("/hello")
    public String hello() {
        return "hello";
    }
}

编写SwaggerConfig.java配置类。

package com.demo.swagger.config;

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

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

访问Swagger的默认地址，可以看到测试页面。

配置Swagger

Swagger的实例Bean是Docket，我们可以通过修改Docket的属性来配置Swagger。修改后的SwaggeConfig.java如下所示。

package com.demo.swagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.RequestHandlerSelectors;
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 {
    @Bean
    public ApiInfo apiInfo() {
        Contact contact = new Contact(
                "WangShaoYang",// 联系人姓名
                "https://blog.csdn.net/qq_36059561",// 联系人链接
                "872452093@qq.com"// 联系人邮箱
        );
        return new ApiInfo(
                "Api Documentation",// 标题
                "Api Documentation",// 描述
                "1.0",// 版本
                "urn:tos",// 组织链接
                contact,// 联系人信息
                "Apache 2.0",// 许可
                "http://www.apache.org/licenses/LICENSE-2.0",// 许可链接
                new ArrayList()// 扩展
        );
    }

    @Bean
    public Docket docket(Environment environment) {
        // 设置需要显示Swagger的环境（假设只需要在dev和test环境开启）
        Profiles profiles = Profiles.of("dev", "test");
        // 检查运行环境是不是profiles里定义的，如果是，返回true，否则，返回false
        boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)// 指定Swagger的版本
                // .enable(flag)// 通过运行环境控制Swagger的开关
                .groupName("WangShaoYang")// 配置Api分组，多个人维护Api的话，可以注入多个Docket对象并指明不同的groupName
                .apiInfo(apiInfo())// 将自定义的ApiInfo应用到Docket中
                .select()// 通过select()方法，配置扫描接口，通过RequestHandlerSelectors指定扫描范围
                // 通过api()方法指定扫描范围
                // .apis(RequestHandlerSelectors.any())// 扫描所有
                .apis(RequestHandlerSelectors.basePackage("com.demo.swagger.controller"))// 按照包扫描（常用）
                // .apis(RequestHandlerSelectors.none())// 都不扫描
                // .apis(RequestHandlerSelectors.withClassAnnotation(Controller.class))// 按照类上的注解扫描
                // .apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))// 按照方法上的注解扫描
                // 通过paths()对接口进行过滤
                // .paths(PathSelectors.ant(""))// 保留符合AntPathMatcher匹配规则的路径
                // .paths(PathSelectors.any())// 全都保留
                // .paths(PathSelectors.none())// 全都不保留
                // .paths(PathSelectors.regex(""))// 保留符合String匹配规则的路径
                .build();
    }

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

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

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

实体配置

创建一个实体类User，并添加一个以User作为返回值的方法用于测试。

package com.demo.swagger.pojo;

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

@ApiModel("实体类")// 为类添加注释
public class User {
    @ApiModelProperty("用户名")// 为属性添加注释
    private String username;
    @ApiModelProperty("密码")
    private String password;

    public User() {
    }

    public User(String username, String password) {
        this.username = username;
        this.password = password;
    }

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}

@GetMapping("/user")
public User getUser() {
    return new User("WangShaoYang", "Password");
}

并不是因为@ApiModel和@ApiModelProperty让实体类显示，是因为有一个以User作为返回值的方法。

常见注解

Swagger注解	说明
@Api(tags=“类的说明”)	作用在类上
@ApiOperation(“接口说明”)	作用在接口上
@ApiModel(“POJO说明”)	作用在POJO类上
@ApiModelProperty(value=“属性说明”, hidden=“true”)	作用在类方法的属性上，可以用hidden隐藏属性
@ApiParam(“参数说明”)	作用在参数、方法和字段上，类似@ApiModelProperty

@ApiOperation("post接口")
@PostMapping("/testPost")
@ResponseBody
public User testPost(
        @ApiParam("用户名") @RequestParam String username,
        @ApiParam("密码") @RequestParam String password) {
    return new User(username, password);
}