Swagger 学习笔记 | Swagger 简介 | Springfox 简介 | Springfox 2.9.2 常用注解 | Spring Boot 整合 Swagger2 案例

一、Swagger 简介

---

OpenAPI 简介

OpenAPI 规范（以前称为 Swagger 规范）是 REST API的API 描述格式。OpenAPI 文件可以描述整个 API，包括：
1）可用端点 ( /users) 和每个端点上的操作 ( GET /users, POST /users)
2）操作参数 每个操作的输入和输出
3）身份验证方法
4）联系信息、许可、使用条款和其他信息
API 规范可以用 YAML 或 JSON 编写

Swagger 简介

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。主要的 Swagger 工具包括：
1）Swagger Editor – 基于浏览器的编辑器，可以在其中编写 OpenAPI 规范
2）Swagger UI – 将 OpenAPI 规范呈现为交互式 API 文档
3）Swagger Codegen – 从 OpenAPI 规范生成服务器存根和客户端库

Swagger 作用

支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术

提供 Web 页面在线测试 API：Swagger 生成的文档支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即
可在线测试接口

二、Springfox 简介

---

Springfox 介绍文章

Springfox 是一个使用Java语言开发开源的API Doc的框架， 它的前身是swagger-springmvc，可以将我们的Controller中的方法以文档的形式展现。官方定义为： Automated JSON API documentation for API’s built with Spring。

Springfox 目前有1、2、3三种版本，从v3版本开始则有较大变化，据官方文档介绍，变化如下：

• 删除早期版本的一些依赖。特别是删除springfox-swagger2和springfox-swagger-ui依赖。

• 删除 @EnableSwagger2 注释

• 添加 springfox-boot-starter 支持springboot使用的起步依赖

• Springfox 3.x 删除了对 guava 和其他第三方库的依赖（但仍然依赖于 spring 插件和开放 api 库，用于注释和模型）

Springfox 的作用

1）将前后端有效分离，并保证了API与文档的实时同步
2）使用springfox生成的接口文档直观可视，支持查看各个接口需要的参数和返回结果
3）springfox支持在线测试，可实时检查参数和返回值

接下来主要以v2版本为主。

三、Springfox2.9.2 常用注解

---

Springfox官方配置文档

@Api

作用：标记类，控制整个类生成接口信息的内容，通常写在MVC中的控制器类上。

常用参数说明：

• tags，类的名称，可以有多个值，定义几个别名，在UI视图中就会显示几个控制器访问菜单
• description，描述，已过时

使用案例：

@RestController
@RequestMapping("/user")
@Api(tags = {"用户控制层"}, description = "描述被弃用了，但依然可以使用")
public class UserController{
	...
}

@ApiOperation

作用：标记方法，将方法显示到Swagger生成的文档中

常用参数说明：

• value，方法的名称
• notes，方法的记录
• httpMethod, 请求方式

使用案例：

@ApiOperation(value = "用户注册", httpMethod = "POST")
@PostMapping("/register")
public R<User> register(User user){
    return userService.register(user) ?
            R.success("注册成功", user)
                : R.fail("注册失败", new User());
}

@ApiParam

作用：描述参数，作用于方法中的参数，将参数的描述显示到文档中

常用参数说明：

• name，参数名
• value，参数描述
• require， true/false，表示参数是否必要

使用案例：

@ApiOperation(value = "用户注册", httpMethod = "POST")
@PostMapping("/register")
public R<User> register(@ApiParam(name="用户(user)", value = "注册的用户信息") User user){
    return userService.register(user) ?
            R.success("注册成功", user)
                : R.fail("注册失败", new User());
}

@ApiIgnore

作用：忽略，当前注解描述的方法或类型，不生成API帮助文档

使用案例：

@ApiIgnore
@ApiOperation(value = "用户注册", httpMethod = "POST")
@PostMapping("/register")
public R<User> register(@ApiParam(name="用户(user)", value = "注册的用户信息") User user){
    ...
}

@ApiImplicitParam

作用：作用于@Api类中的方法，用于描述方法中的单个参数

常用参数说明：

• name，参数名，需要与方法中的参数名对应
• value，参数描述
• require， true/false，表示参数是否必要
• dataType，参数类型
  使用案例：

 @ApiOperation(value = "用户注册", httpMethod = "POST")
 @ApiImplicitParam(name = "user", value = "注册的用户信息")
 @PostMapping("/register")
 public R<User> register(@ApiParam(name="用户", value = "注册的用户信息") User user){
     ...
 }

@ApiImplicitParams

作用：作用于@Api类中的方法，用于描述方法中的多个参数

常用参数说明：{ @ApiImplicitParam(…) , @ApiImplicitParam(…) }

@ApiOperation(value = "修改用户信息", httpMethod = "POST")
@ApiImplicitParams({
        @ApiImplicitParam(
                name = "userId", value = "用户的ID",
                required = true, dataType = "long", paramType = "path"),
        @ApiImplicitParam(
                name = "user", value = "修改后的用户信息(id不可更改)",
                dataType = "User", paramType = "query")
})
@PostMapping("/update/{userId}")
public R<Long> modify(@PathVariable Long userId, User user){
    ...
}

@ApiModel

作用：描述一个实体类型，这个实体类型如果称为任何一个生成api帮助文档方法的返回值类型时，该注解被解析。

常用参数说明：

• vlaue，实体类的名称（唯一）
• description，实体类的描述

@ApiModelProperty

作用：描述@ApiModel实体类型中的属性

常用参数说明：

• value，参数的名称（唯一）
• name，参数的名称
• required，true/false，表示属性是否必须
• example, 值的范例
• hidden, true/false，表示是否隐藏

使用案例：

package cn.uni.rbac.po;

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

import java.io.Serializable;
import java.util.List;

@Data
@ApiModel("用户表实体对象")
public class User implements Serializable {
    @ApiModelProperty("用户ID")
    private Long id;

    @ApiModelProperty("用户名")
    private String name;

    @ApiModelProperty("用户密码")
    private String password;

    @ApiModelProperty("盐")
    private String salt;

    @ApiModelProperty("外键: 角色表对象")
    private List<Role> roleList;
}

四、SpringBoot 整合 Swagger2

---

接下来使用SpringBoot 整合 Swagger2，实现简单的API文档生成

案例的项目结构：

运行结果：

版本选型：

• IDEA 2022 专业版
• Maven3.8.4
• JDK 8
• SpringBoot 2.6.9
• Springfox 2.9.2
• Springfox-ui 2.9.2

4.1 引入Maven依赖

pom.xml

<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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0modelVersion>
    <parent>
        <groupId>org.springframework.bootgroupId>
        <artifactId>spring-boot-starter-parentartifactId>
        <version>2.6.9version>
        <relativePath/> 
    parent>
    <groupId>cn.unigroupId>
    <artifactId>swagger-demoartifactId>
    <version>0.0.1-SNAPSHOTversion>
    <name>swagger-demoname>
    <description>swagger-demodescription>
    <properties>
        <java.version>1.8java.version>
    properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.bootgroupId>
            <artifactId>spring-boot-starter-webartifactId>
        dependency>
        
        <dependency>
            <groupId>org.projectlombokgroupId>
            <artifactId>lombokartifactId>
            <optional>trueoptional>
        dependency>
        <dependency>
            <groupId>org.springframework.bootgroupId>
            <artifactId>spring-boot-starter-testartifactId>
            <scope>testscope>
        dependency>

        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-swagger-uiartifactId>
            <version>2.9.2version>
        dependency>
        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-swagger2artifactId>
            <version>2.9.2version>
        dependency>

    dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.bootgroupId>
                <artifactId>spring-boot-maven-pluginartifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombokgroupId>
                            <artifactId>lombokartifactId>
                        exclude>
                    excludes>
                configuration>
            plugin>
        plugins>
    build>
project>

4.2 项目配置

Springfox Swagger2 配置：config/SwaggerConfig.java

package cn.uni.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
// http://localhost:8080/swagger-ui/index.html
public class SwaggerConfig {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2) //
                .select()
                // 设置扫描的路径
                .apis(RequestHandlerSelectors.basePackage("cn.uni.controller"))
                .build();
    }
}

SpringMVC配置，为解决SpringBoot高版本的mvc路径匹配规则与Springfox-Swagger-ui 冲突，需要进行以下的配置：config/WebMvcConfig.java

package cn.uni.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;

@Configuration
public class WebMvcConfig extends WebMvcConfigurationSupport {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations(
                "classpath:/static/");
        // 配置 swagger 的拦截器，SpringBoot2.6.x 兼容 Swagger 2.9.2 必备
        registry.addResourceHandler("swagger-ui.html", "doc.html").addResourceLocations(
                "classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations(
                "classpath:/META-INF/resources/webjars/");
        super.addResourceHandlers(registry);
    }
}

4.3 数据模型

用户实体类：pojo/po/User.java

package cn.uni.pojo.po;

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

@ApiModel(value = "用户", description = "用户实体类")
@Data
public class User {
    @ApiModelProperty(name="用户ID(id)", example = "1")
    private Integer id;
    @ApiModelProperty(name = "用户名称(username)", example = "uni")
    private String username;
    @ApiModelProperty(name = "用户密码(password)", example = "123456")
    private String password;
}

前后端交互类：pojo/po/R.java

package cn.uni.pojo.po;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.io.Serializable;

/**
 * Restful Response  RestFul风格的统一数据响应类
 * TODO 实现 前端和后端通过JSON数据的传输
 */
@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value = "前后端交互")
public class R<T> implements Serializable {

    @ApiModelProperty(value = "响应代码")
    private Integer code;
    @ApiModelProperty(value="响应的信息")
    private String msg;
    @ApiModelProperty(value="响应的数据")
    private T data;

    /**
     * 成功的响应
     * @param msg   响应信息
     * @param data  响应数据
     * @return  R对象
     * @param   数据的类型
     */
    public static<T> R<T> success(String msg, T data){
        return new R<T>(200, msg, data);
    }
    /**
     * 失败的响应
     * @param msg   响应信息
     * @param data  响应数据
     * @return  R对象
     * @param   数据的类型
     */
    public static<T> R<T> fail(String msg, T data){
        return new R<T>(400, msg, data);
    }
    /**
     * 自定义的响应
     * @param msg   响应信息
     * @param data  响应数据
     * @return  R对象
     * @param   数据的类型
     */
    public static<T> R<T> custom(int code, String msg, T data){
        return  new R<T>(code, msg, data);
    }
}

4.4 Controller层

这里模拟注册与登录，调用接口后直接返回成功的信息和请求的数据。

package cn.uni.controller;

import cn.uni.pojo.po.User;
import cn.uni.pojo.po.R;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@Api(tags = "用户操作相关的控制层")
@RestController
@RequestMapping("/user")
public class UserController {
    @ApiOperation(value = "用户注册", httpMethod = "POST")
    @ApiImplicitParam(name = "user", value = "注册的用户信息")
    @PostMapping("/register")
    public R<User> register(@ApiParam(name="用户", value = "注册的用户信息") User user){
        return R.success("注册成功", user);
    }
    @ApiOperation(value = "用户登录", httpMethod = "POST")
    @PostMapping("/login")
    public R<User> login(User user){
        return R.success("登录成功", user);
    }
}

4.5 SpringBoot 启动类

App.java

package cn.uni;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

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

4.6 运行并测试案例