本文介绍了Swagger的基本概念，如OpenAPI规范和Swagger工具的作用。接着，详细讲解了Springfox框架，包括其版本变化及核心注解的使用。最后，展示了如何在SpringBoot项目中整合Swagger2，包括引入依赖、配置和创建API文档的示例。
文章目录
一、Swagger 简介
OpenAPI 规范（以前称为 Swagger 规范）是 REST API的API 描述格式。OpenAPI 文件可以描述整个 API，包括：
1）可用端点 ( /users) 和每个端点上的操作 ( GET /users, POST /users)
2）操作参数 每个操作的输入和输出
3）身份验证方法
4）联系信息、许可、使用条款和其他信息
API 规范可以用 YAML 或 JSON 编写
Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。主要的 Swagger 工具包括：
1）Swagger Editor – 基于浏览器的编辑器，可以在其中编写 OpenAPI 规范
2）Swagger UI – 将 OpenAPI 规范呈现为交互式 API 文档
3）Swagger Codegen – 从 OpenAPI 规范生成服务器存根和客户端库
支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术
提供 Web 页面在线测试 API：Swagger 生成的文档支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即
可在线测试接口
二、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 库，用于注释和模型）
1）将前后端有效分离，并保证了API与文档的实时同步
2）使用springfox生成的接口文档直观可视，支持查看各个接口需要的参数和返回结果
3）springfox支持在线测试，可实时检查参数和返回值
接下来主要以v2版本为主。
三、Springfox2.9.2 常用注解
作用：标记类，控制整个类生成接口信息的内容，通常写在MVC中的控制器类上。
常用参数说明：
- tags，类的名称，可以有多个值，定义几个别名，在UI视图中就会显示几个控制器访问菜单
- description，描述，已过时
使用案例：
@RestController
@RequestMapping("/user")
@Api(tags = {"用户控制层"}, description = "描述被弃用了，但依然可以使用")
public class UserController{
...
}
作用：标记方法，将方法显示到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());
}
作用：描述参数，作用于方法中的参数，将参数的描述显示到文档中
常用参数说明：
- 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());
}
作用：忽略，当前注解描述的方法或类型，不生成API帮助文档
使用案例：
@ApiIgnore
@ApiOperation(value = "用户注册", httpMethod = "POST")
@PostMapping("/register")
public R<User> register(@ApiParam(name="用户(user)", value = "注册的用户信息") User user){
...
}
作用：作用于@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){
...
}
作用：作用于@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){
...
}
作用：描述一个实体类型，这个实体类型如果称为任何一个生成api帮助文档方法的返回值类型时，该注解被解析。
常用参数说明：
- vlaue，实体类的名称（唯一）
- description，实体类的描述
作用：描述@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
<?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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.6.9</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>cn.uni</groupId>
<artifactId>swagger-demo</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>swagger-demo</name>
<description>swagger-demo</description>
<properties>
<java.version>1.8</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<optional>true</optional>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<excludes>
<exclude>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</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 <T> 数据的类型
*/
public static<T> R<T> success(String msg, T data){
return new R<T>(200, msg, data);
}
/**
* 失败的响应
* @param msg 响应信息
* @param data 响应数据
* @return R对象
* @param <T> 数据的类型
*/
public static<T> R<T> fail(String msg, T data){
return new R<T>(400, msg, data);
}
/**
* 自定义的响应
* @param msg 响应信息
* @param data 响应数据
* @return R对象
* @param <T> 数据的类型
*/
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 运行并测试案例
扫一扫
2123
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
