文章目录

一、Swagger 简介
二、Springfox 简介
三、Springfox2.9.2 常用注解
四、SpringBoot 整合 Swagger2
- 4.1 引入Maven依赖
- 4.2 项目配置
- 4.3 数据模型
- 4.4 Controller层
- 4.5 SpringBoot 启动类
- 4.6 运行并测试案例

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

<?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 {@Beanpublic 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 {@Overridepublic 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 运行并测试案例

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

JavaScript学习笔记01【基础——简介、基础语法、运算符、特殊语法、流程控制语句】
w3school 在线教程:https://www.w3school.com.cn JavaScript学习笔记01[基础--简介.基础语法.运算符.特殊语法.流程控制语句][day01] JavaS ...
HoloLens开发学习笔记(一)：HoloLens简介
HoloLens开发学习笔记(一):HoloLens简介一.HoloLens简介 Microsoft HoloLens是Windows Holographic的使用主要设备.HoloLens是一个W ...
OPENMP学习笔记（1）——简介，模型，运行
OPENMP学习笔记(1)--简介,模型,运行简介: OpenMP的英文全称是Open Multiprocessing,一种应用程序接口(API,即Application Program Inter ...
JavaWeb学习笔记2 —— Web服务器简介
JavaWeb学习笔记2 -- Web服务器简介参考教程B站狂神https://www.bilibili.com/video/BV12J411M7Sj 相关技术 ASP: 微软:国内最早流行的就是A ...
小猫爪：S32K3学习笔记09-S32K3之Safety简介
小猫爪:S32K3学习笔记09-S32K3之Safety简介 1 前言 2 Safety相关硬件介绍 3 Safety相关软件介绍 4 Safety文章目录 END 1 前言接下来,就要开始进学 ...
Spring Boot 整合 Swagger
一.为什么要用 Swagger 现在的开发模式,一般都是前后端分离的,开发接口文档就显得尤为重要,前端人员需要按照后端的功能文档调用对应的接口.在没有使用 API 文档之前,很多公司都是在纸或者 Ma ...
HiveQL学习笔记（二）：Hive基础语法与常用函数
本系列是本人对Hive的学习进行一个整理,主要包括以下内容: 1.HiveQL学习笔记(一):Hive安装及Hadoop,Hive原理简介 2.HiveQL学习笔记(二):Hive基础语法与常用函数 ...
Spring Boot基础学习笔记08：Spring Boot整合Redis
文章目录零.学习目标 1.熟悉Redis相关概念 2.掌握使用Spring Boot整合Redis 一.Redis概述 1.Redis简介 2.Redis优点 (1)存取速度快 (2)数据类型丰富 ...
Spring Boot基础学习笔记07：Spring Boot整合JPA
文章目录零.学习目标 1.熟悉Spring Data JPA基本语法和使用 2.掌握Spring Boot与JPA的整合使用一.Spring Data JPA概述 1.Spring Data JP ...

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

文章目录

一、Swagger 简介

二、Springfox 简介

三、Springfox2.9.2 常用注解

四、SpringBoot 整合 Swagger2

4.1 引入Maven依赖

4.2 项目配置

4.3 数据模型

4.4 Controller层

4.5 SpringBoot 启动类

4.6 运行并测试案例

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

最新文章

热门文章