2025年swagger使用教程（swagger2使用）

大家好，我是讯享网，很高兴认识大家。

 <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <path stroke-linecap="round" d="M5,0 0,2.5 5,5z" id="raphael-marker-block" style="-webkit-tap-highlight-color: rgba(0, 0, 0, 0);"></path> </svg>

讯享网

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务的接口文档。

目前的项目基本都是前后端分离，后端为前端提供接口的同时，还需同时提供接口的说明文档。但我们的代码总是会根据实际情况来实时更新，这个时候有可能会忘记更新接口的说明文档，造成一些不必要的问题。

用人话说，swagger就是帮你写接口说明文档的。

1, 前后端分离的项目

前后端分离式开发
在这里插入图片描述
讯享网

纯粹后端的java开发人员,不编写页面代码, 只需要写接口( 这里的接口不是java中的interface )

在SpringMVC的控制层Controller类的方法里, 不写转页( 包括内部转, 重定向 ),

都是通过 @ResponseBody, 返回JSON格式的数据

所以 Controller 类上的注解由@Controller, 改为 @RestController ( @Controller + @ResponseBody )

2, 什么是接口

接口就是制定一个协议, 给前端开发人员调用后端功能的参考. 可能包括的内容 :

协议介绍 http 还是 https https请求需要SSL证书请求名 url 或者 uri 请求方式 get, post, put, delete等等参数列表包括类型和传值方式返回类型返回格式, 状态码, 错误消息, 数据

3, 举例说明

例如:

模块名称: 用户登录

请求方式: post

请求名: /login/auth

参数

参数名类型说明是否必须 username String(20) 用户名是 password String(20) 密码是 remember Interger 记住我, 1-记住,0-不记住, 默认按0处理否

讯享网

或者

如果是由后端人员来维护这些信息, 有个非常大的缺点,

就是如果对这个方法做了修改, 例如添加了一个新的参数, 则需要修改这个接口文档.

基于这个缺点, 诞生了一个技术, 接口文档自动生成工具-swagger

即, 整个接口文档内容, 不需要手动编写了, 而是通过程序自动生成

4, 返回JSON格式

讯享网

最少要求包含3个属性,可以很多

1, 引入依赖包

讯享网

2, 加入Swagger2的配置类

主要配置Swagger2注解的扫描路径

次要配置一些说明信息

apis(RequestHandlerSelectors.basePackage())

表示swagger2的注解, 必须写在com.yuan的同级包或者子包里, 否则不识别

3, 开启swagger2, 添加下面的注解到全局配置类上(

例如 : 启动类或者当前配置类

讯享网

1, 默认界面的请求路径

2, layer主题

讯享网

请求路径

3, bootstrap版主题

讯享网

请求路径

讯享网

swagger不会参与业务开发,和业务代码是完全解耦的, 没有任何耦合

原始代码

swagger的注解只是给你的类, 方法, 参数, 属性添加注释而已.

1, 给控制层添加注释

讯享网

2, 控制层的方法添加中文注释

3,给参数加注释

讯享网

4, 隐藏一个参数, 用@ApiIgnore

5, 添加完成

这样可以打开浏览器进行

6, 给类里的属性添加注释

6.1 给类加一个注解

讯享网

6.2 给属性添加注解

0, RESTFUL是一种网络应用程序的设计风格和开发方式

REST（英文：Representational State Transfer，简称REST）描述了一个架构样式的网络系统，比如 web 应用程序。

通常 get 查询 post 添加 put/patch 修改 delete 删除

1, 选择请求方式

在接口系统里, 不要只写@RequestMapping(value = “/user/{id}”), 同时要指明请求方式 method

讯享网

2.1, 传统方式接值方式

SpringMVC 路径传参

接值

讯享网

2.2, 路径传参

接值

讯享网

页面发出请求

controller 代码

讯享网

2.3, 对象传参

封装对象(json)

参数接值

paramType：表示参数放在哪个地方

类型解释 header 指该参数需在请求头传参, 请求参数的获取：@RequestHeader(代码中接收注解) query 指该参数需在请求URL传参 , 请求参数的获取：@RequestParam(代码中接收注解) path 指该参数为路径参数, （用于restful接口）–>请求参数的获取：@PathVariable(代码中接收注解) body 指该参数需在请求JSON传参, 请求参数的获取：@RequestBody(代码中接收注解) form （不常用）

1, query 类型

讯享网

2, path 类型

3, form 类型 (1)

讯享网

4, form 类型 (2) 带文件上传

4.1,上传单一文件

4.2,上传多个文件

只能 bootstrap版主题或者 postman 可以进行测试

讯享网

5, body参数 (1)

指该参数需在请求JSON传参

5.1, 接值

只需要在参数前面加入注解@RequestBody即可. 但是一定要记住, 这个注解在参数里只能使用1次.

5.2, 传值

讯享网

在这里插入图片描述

6, body参数 (2)

6.1, 接值

6.2, 传值

讯享网

在这里插入图片描述

7, 通过 @ModelAttribute 接值

post请求中使用@modelAttribute接收参数，在swagger-ui文档中paramterType 是query

7.1, 实体类加注解

7.2, controller中接值

讯享网

7.3, 传值

在这里插入图片描述

8, 传递集合

8.1, 通过Array数组 controller中接值

8.2, 通过List controller中接值

讯享网

8.3, 传值通过 , 分隔

在这里插入图片描述

2025年swagger使用教程（swagger2使用）

1, 前后端分离的项目

2, 什么是接口

3, 举例说明

4, 返回JSON格式

1, 引入依赖包

2, 加入Swagger2的配置类

3, 开启swagger2, 添加下面的注解到全局配置类上(

1, 默认界面的请求路径

2, layer主题

3, bootstrap版主题

1, 给控制层添加注释

2, 控制层的方法添加中文注释

3,给参数加注释

4, 隐藏一个参数, 用@ApiIgnore

5, 添加完成

6, 给类里的属性添加注释

6.1 给类加一个注解

6.2 给属性添加注解

0, RESTFUL是一种网络应用程序的设计风格和开发方式

1, 选择请求方式

2.1, 传统方式接值 方式

2.2, 路径传参

2.3, 对象传参

1, query 类型

2, path 类型

3, form 类型 (1)

4, form 类型 (2) 带文件上传

4.1,上传单一文件

4.2,上传多个文件

5, body参数 (1)

5.1, 接值

5.2, 传值

6, body参数 (2)

6.1, 接值

6.2, 传值

7, 通过 @ModelAttribute 接值

7.1, 实体类加注解

7.2, controller中接值

7.3, 传值

8, 传递集合

8.1, 通过Array数组 controller中接值

8.2, 通过List controller中接值

8.3, 传值 通过 , 分隔

相关推荐

2.1, 传统方式接值方式

8.3, 传值通过 , 分隔