Swagger 3.0

本swagger之以org.springdoc来学习，spring boot和swagger依赖关系springdoc.org
官网地址：API Documentation & Design Tools for Teams | Swagger

依赖

spring boot 2.x整合swagger 3.0 的maven依赖

 <dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-ui</artifactId><version>1.6.15</version></dependency>
<!-- swagger需要的webjars依赖 --><dependency><groupId>org.webjars</groupId><artifactId>jquery</artifactId><version>3.6.2</version></dependency>

spring boot 3.x整合swagger 3.0 的maven依赖

<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-webflux-ui</artifactId><version>1.6.15</version>
</dependency>

1：swagger是什么

OpenAPI是规范；Swagger是实现规范的工具open api 简介
OpenApi是一个业界的 api 文档标准，一个规范。好比java里面一个抽象的概念，即是一个抽象类，只是提供了一个api文档规范的抽象方法。该方法目前被两大非官方实现了，一个是springfox，另一个是springdoc。

最流行的api框架
可以在线、自动、更新生成api文档生成器，来自于前后端分离
可以在线测试api接口
可以和很多技术使用

2：swagger-ui

没有设置项目地址默认就是http://localhost:8080/swagger-ui/index.html

2.1swagger自定义页面

配置一个注解只保留有用的页面信息

效果

注解

@OpenAPIDefinition(info = @Info(title = "用户登录API文档",description = "测试API文档",version = "version-1.0",contact = @Contact(name = "xxl",email = "3578144921@qq.com",url = "https://gitee.com/com_xxl/spring-boot-study")),//这个服务地址就是swagger-ui测试接口的地址servers = @Server(url = "http://localhost:8080/",description = "默认地址")
)

3：spring-boot-swagger注解

3.1、@EnableSwagger2

开启swagger 功能，让swagger 注解生效但版本是2.0

范围

@Target(value = {java.lang.annotation.ElementType.TYPE})

3.2、@OpenAPIDefinition

范围

@Target({ElementType.TYPE, ElementType.PACKAGE, ElementType.ANNOTATION_TYPE})

@OpenAPIDefinition全局只能定义一个，主要配置文档信息和安全配置，这里列举了常用的请求头携带token的安全配置模式
@OpenAPIDefinition下的info属性配置文档信息
@OpenAPIDefinition下的security配置认证方式，name属性引入自定义的认证模式
@SecurityScheme注解就是自定义的认证模式，配置请求头携带token

3.3、@Tag

范围

@Target({ElementType.METHOD, ElementType.TYPE, ElementType.ANNOTATION_TYPE})

常用属性

@Tag(name = "接口名字", description = "接口描述") //针对类、接口

如果注解了java接口，这个接口又被controller继承了则会包含controller的请求路径

3.4、 @Operation

此注解包含@Parameter，@ApiResponse
描述方法的注解

范围

@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})

Api类

@Operation(summary = "登录接口",description = "用于用户登录的接口"
)
String login(String username,String password);

3.5、@Schema

暂时的用法就是用在dto对象

范围

@Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.TYPE, ElementType.ANNOTATION_TYPE})

描述对象信息

swagger-ui

实体类

@Data
@AllArgsConstructor
@NoArgsConstructor
@Schema(name = "User" ,title = "用户数据传输对象")
public class User {@Schema(title = "用户姓名")private String name;@Schema(title = "用户爱好")private String hobby;
}

3.6、@ApiResponse

设置返回什么，建议用在方法上

范围

@Target({ElementType.METHOD, ElementType.TYPE, ElementType.ANNOTATION_TYPE})

如果配合@ControlleerAdvice使用，如全局的异常类捕捉了400的错误就会加入所有方法中，然后会被记录在swagger-ui

案例

@ApiResponse(description = "登录成功",content = @Content(mediaType = "application/json;charset=utf-8"),responseCode = "200")
@ApiResponse(description = "页面未找到",content = @Content(mediaType = "application/json;charset=utf-8"),responseCode = "404")
@ApiResponse(description = "服务器代码错误",content = @Content(mediaType = "application/json;charset=utf-8"),responseCode = "500")String login(String username,String password);

3.7、@Parameter

描述属性、参数信息，一般用于参数的描述
name与参数名一致

范围

@Target({PARAMETER, METHOD, FIELD, ANNOTATION_TYPE})

案例

@Parameter(name = "username",description = "用户名",required = false)
@Parameter(name = "password",description = "用户密码",required = false)
String login(String username,String password);

4：spring-boot-swagger的yml配置文件

比较常用的

springdoc:api-docs:#是否开启文档功能关系到swagger-ui能否开启enabled: true#swagger后端请求地址，查看sawgger所有配置path: /api-docsswagger-ui:#自定义swagger前端请求路径，输入http：127.0.0.1:8080/test会自动重定向到swagger页面path: /test#包扫描路径，注册api，
#  packages-to-scan:  "com.xxl.controller"#这里定义了两个分组，可定义多个，也可以不定义group-configs:#分组名- group: admin#按包路径匹配：范围大packagesToScan:  "com.xxl.controller.impl"#分组名- group: user#按请求路径匹配：范围小paths-to-match: "/user/**"#排除请求路径packages-to-exclude:- "/admin"

5：spring-boot-swagger

自动识别有没有请求，比如你写了controller但是没有设置请求路径，哪怕你加上了swagger注解在ui界面不会显示信息的，因为ui的信息根据请求路径来的
swagger 3-ui在spring-boot中能自动识别swagger注解(只有@Schemas比较特殊)因为只要被spring管理加上是控制器就会自动识别，并不需要开启什么
如果接口使用了实体类就会被识别，在swagger-ui的Schemas区域
可以配合jsr303使用

6：swagger-ui配合jsr校验总结

6.1、get请求

如下还有一种情况就是不在swagger-ui进行测试，而是url请求，就会返回提示信息，在swagger-ui界面测试接口有时的提示信息不是我们想要的

6.2、post请求

Swagger 3.0相关推荐

.Net Core Swagger:Actions require an explicit HttpMethod binding for Swagger 2.0
添加完Swagger包引用后运行报错:Actions require an explicit HttpMethod binding for Swagger 2.0 第一时间想到了父类控制器没有添加 ...
Error while importing Swagger 2.0: (Patchable) path parameters must be required:true
swagger导入postman异常 Error while importing Swagger 2.0: (Patchable) path parameters must be required:t ...
Swagger 3.0 官方教材出炉，野生的可以扔了！
点击"开发者技术前线",选择"星标????" 让一部分开发者看到未来链接:blog.csdn.net/wangzhihao1994/article/detai ...
.NET Core 3.0 webapi集成Swagger 5.0
在项目中引用Swashbuckle.AspNetCore和Swashbuckle.AspNetCore.Filters两个dll,在Startup中的ConfigureServices相关配置代码如下 ...
NETCore2.2/3.0+使用带有权限验证的Swagger
文章目录 Swagger 什么是Swagger NuGet安装 Startup注册Swagger 设置默认首页打开Swagger 为接口添加注释 JWT 什么是JWT 注册授权认证服务 API接口添加 ...
Swagger3.0 天天刷屏，真的香吗？
目录前言官方文档如何说? Spring Boot版本说明添加依赖 springfox-boot-starter做了什么? 撸起袖子就是干? 定制一个基本的文档示例文档如何分组? 如何添加授权信 ...
六、springboot整合swagger
六.springboot整合swagger 简介 swagger 提供最强大,最易用的工具,以充分利用OpenAPI规范. 官网 : https://swagger.io/ 准备工作 pom.xml ...
使用swagger作为restful api的doc文档生成——从源码中去提取restful URL接口描述文档...
初衷记得以前写接口,写完后会整理一份API接口文档,而文档的格式如果没有具体要求的话,最终展示的文档则完全决定于开发者的心情.也许多点,也许少点.甚至,接口总是需要适应新需求的,修改了,增加了,这份 ...
使用 Swagger 文档化和定义 RESTful API
大部分 Web 应用程序都支持 RESTful API,但不同于 SOAP API--REST API 依赖于 HTTP 方法,缺少与 Web 服务描述语言(Web Services Descript ...

Swagger 3.0

Swagger 3.0

1：swagger是什么

2：swagger-ui

2.1swagger自定义页面

3：spring-boot-swagger注解

3.1、@EnableSwagger2

3.2、@OpenAPIDefinition

3.3、@Tag

3.4、 @Operation

3.5、@Schema

3.6、@ApiResponse

3.7、@Parameter

4：spring-boot-swagger的yml配置文件

5：spring-boot-swagger

6：swagger-ui配合jsr校验总结

6.1、get请求

6.2、post请求

Swagger 3.0相关推荐

最新文章

热门文章