Swagger3基本使用

embedded/2024/9/30 0:02:15/

Swagger

课程目标

Swagger简介【了解】

Springboot整合swagger【掌握】

Swagger 常用注解【掌握】

knife4j-Swagger【会用】

一、Swagger3简介

	Swagger 是一系列 RESTful API 的工具，通过 Swagger 可以获得项目的⼀种交互式文档，客户端 SDK 的自 动生成等功能。Swagger 的目标是为 REST APIs  定义一个标准的、与语⾔言无关的接口，使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下，能发现和理解各种服务的功能。当服务通过 Swagger 定义，消费者就能与远程的服务互动通过少量的实现逻辑。Swagger（丝袜哥）是世界上最流行的 API 表达工具。

OpenAPI阶段的Swagger也被称为Swagger 3.0。在Swagger 2.0后，Swagger规范正式更名为OpenAPI规范，并且根据OpenAPI规范的版本号进行了更新。因此，Swagger 3.0对应的就是OpenAPI 3.0版本，它是Swagger在OpenAPI阶段推出的一个重要版本。与前几个版本相比，Swagger 3.0更加强调对RESTful API的支持和规范化，提供了更丰富和灵活的定义方式，并且可以用于自动生成文档、客户端代码、服务器代码和测试工具等。

二、Springboot整合swagger3

	使用 Spring Boot 集成 Swagger 的理念是，使用用注解来标记出需要在 API 文档中展示的信息，Swagger  会根据项目中标记的注解来生成对应的 API 文档。Swagger 被号称世界上最流行的 API 工具，它提供了 API  管理的全套解决方案，API 文档管理需要考虑的因素基本都包含，这里将讲解最常用的定制内容。

  • 添加依赖


    org.springdoc
    springdoc-openapi-starter-webmvc-ui
    2.6.0


    org.springdoc
    springdoc-openapi-starter-webmvc-api
    2.6.0

  • 创建 SwaggerConfig 配置类
    /**
    * swagger3配置类
    */
    @Configuration
    public class SwaggerConfig {

        @Beanpublic OpenAPI openAPI(){return new OpenAPI().info(this.getInfo());}public Info getInfo(){return new Info().title("Springboot集成Swagger3") //标题.description("Springboot集成Swagger3接口说明") //项目描述.contact(new Contact().name("蜗牛学院")) //作者.version("V1.0"); //版本号}
}

  • 访问swagger
    启动项目后输入：http://localhost:8080/swagger-ui/index.html 可看到swagger页面
    如果在访问 /swagger-ui/index.html 时出现 404 。这是因为，当你访问 .html 等静态资源时，Spring MVC 默认是在你自己项目的 resources/static 目录下去找它们，如果没有，自然就是 404 。而 swagger 相关的 .html 等静态资源是在依赖包含的 swagger-ui 项目（jar包） 下。所以，你需要通过静态资源配置来『告诉』Spring MVC 当收到 swagger 相关的静态资源访问时，去对应的这个目录下找它们。
    /**
    * spring mvc配置类
    */
    @Configuration //项目启动时加载此类
    public class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler(“/swagger-ui/**”)
    .addResourceLocations(“classpath:/META-INF/resources/webjars/springfox-swagger-ui/”);
    }
    }

  • 配置访问路径
    swagger的访问路径可以自己更改

    • 默认路径
      springdoc:
      api-docs:
      path: /v3/api-docs
      swagger-ui:
      path: /swagger-ui.html #可以改成自己喜欢的路径，如/doc.html

三、knife4j-Swagger

knife4j 是 Swagger 生成 API 文档的增强解决方案，最主要是 knife4j 提供了动态字段注释功能实现 Map 来接收参数这个的接口文档生成，忽略参数属性来实现同一个实体类对不同接口生成不同的文档

  • 添加依赖
    前面swagger3的依赖不需要了


    com.github.xiaoymin
    knife4j-openapi3-jakarta-spring-boot-starter
    4.3.0

  • 创建配置类
    /**
    * swagger3配置类
    */
    @Configuration
    public class SwaggerConfig {
    @Bean
    public OpenAPI openAPI(){
    return new OpenAPI().info(this.getInfo());
    }

        public Info getInfo(){return new Info().title("Springboot集成Swagger3") //标题.description("Springboot集成Swagger3接口说明") //项目描述.contact(new Contact().name("蜗牛学院")) //作者.version("V1.0"); //版本号}
}

    启动项目后通过：http://127.0.0.1:8080/doc.html 访问knife4j页面

四、Swagger3 常用注解

Swagger 通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息等。

1、@Tag

作用于类上，一般用来对controller类进行说明

语法：  @Tag(name = "用户接口", description = "用户管理相关接口")示例 ：
@RestController
@Tag(name="用户操作")
public class UserController {}

2、@Operation

作用于Controller的方法上。用于对controller方法进行说明

语法：
@Operation(summary = "操作摘要",description = "操作的详细描述",operationId = "operationId",tags = "tag1",parameters = {@Parameter(name = "param1", description = "参数1", required = true),@Parameter(name = "param2", description = "参数2", required = false)})示例 ：@GetMapping("/user/list")@Operation(summary = "用户列表")public List<User> userList(){return userService.finUser();}

参数说明：

  • summary：简短描述
  • description ：更详细的描述
  • hidden：是否隐藏
  • tags：标签，用于分组API
  • operationId：操作的唯一标识符，建议使用唯一且具有描述性的名称
  • parameters：指定相关的请求参数，使用 @Parameter 注解来定义参数的详细属性。
  • requestBody：指定请求的内容，使用 @RequestBody 注解來指定请求的类型。
  • responses：指定操作的返回内容，使用 @ApiResponse 注解定义返回值的详细属性。

3、@Parameters

作用于Controller的方法上。@Parameters注解中包含多个 @Parameter 注解，通过@Parameter注解对controller方法中的非对象类型形参进行说明

语法：
@Parameters({@Parameter(name = "param1",description = "description",required = true,in = ParameterIn.PATH,schema = @Schema(type = "string")),@Parameter(name = "param2",description = "description",required = true,in = ParameterIn.QUERY,schema = @Schema(type = "integer"))
})示例：@GetMapping("/user/query")@Operation(summary = "根据条件查询用户")@Parameters({@Parameter(name="username",in= ParameterIn.QUERY,description = "用户名",required = true,schema = @Schema(type ="String")),@Parameter(name="age",in= ParameterIn.QUERY,description = "年龄",required = true,schema = @Schema(type ="Integer"))})public List<User> queryUser(@RequestParam(value = "username",required = true,defaultValue = "") String username,@RequestParam(value = "age",required = true,defaultValue = "0") Integer age){return userService.finUser();}

@Parameter参数说明：

  • name : 指定的参数名
  • in：参数来源，可选 query、header、path 或 cookie，默认为空，表示忽略
  • ParameterIn.QUERY 请求参数
  • ParameterIn.PATH 路径参数
  • ParameterIn.HEADER header参数
  • ParameterIn.COOKIE cookie 参数
  • description：参数描述
  • required：是否必填，默认为 false
  • schema ：参数的数据类型。如 schema = @Schema(type = “string”)

4、@ApiResponses

作用于Controller的方法上。@ApiResponses包含多个@ApiResponse。通过@ApiResponse对controller方法的返回值进行说明

语法：
@ApiResponse(responseCode = "200", description = "查询成功", 
content = @Content(schema = @Schema(implementation = User.class)))
@ApiResponse(responseCode = "404", description = "查询失败")示例：@GetMapping("/user/query")@Operation(summary = "根据条件查询用户")@ApiResponses({@ApiResponse(responseCode = "2000",description = "多条件查询成功",content = @Content(schema = @Schema(implementation = List.class))),@ApiResponse(responseCode = "5000",description = "多条件查询失败成功")})public ResponseResult<List<User>> queryUser(){return new ResponseResult<>(2000,"OK",null);}

@ApiResponse参数说明：

  • responseCode：响应的 HTTP 状态码
  • description：响应信息的描述
  • content：响应的内容

5、@Schema

用于FO的类上。用于对controller中对象参数对应的FO对象的属性进行说明

  • vo实体类
    @Data
    @Tag(name = “用户Vo”, description = “接收用户信息实体类”)
    public class UserVo implements Serializable {
    private static final long serialVersionUID = 1L;
    @Schema(name = “id”, type = “Integer”,description = “用户id”,defaultValue =“0”)
    private Integer id;
    @Schema(name = “username”, type = “String”,description = “用户真实姓名”,defaultValue = “”)
    private String username;
    @Schema(name = “birthday”, type = “LocalDateTime”,description = “生日”,defaultValue = “”)
    private LocalDateTime birthday;
    @Schema(name = “sex”, type = “String”,description = “性别”,defaultValue = “男”)
    private String sex;
    }
    参数说明：
    name：名称
    title：标题
    description：描述
    example：示例值
    required：是否为必须
    format：属性的格式。如 @Schema(format = “email”)
    maxLength 、 minLength：指定字符串属性的最大长度和最小长度
    maximum 、 minimum：指定数值属性的最大值和最小值
    pattern：指定属性的正则表达式模式
    type： 数据类型（integer，long，float，double，string，byte，binary，boolean，date，dateTime，password），必须是字符串。如 @Schema=(type=“integer”)
    implementation ：具体的实现类，可以是类本身，也可以是父类或实现的接口。
  • controller
    @PostMapping(“/user/add”)
    @Operation(summary = “添加用户”)
    public ResponseResult<List> addUser(@RequestBody UserFo userFo){
    return new ResponseResult<>(2000,“OK”,null);
    }

五、spring security放行swagger3

修改security配置类

 /*** spring security过滤器链配配置* @param http* @return* @throws Exception*/@Beanpublic SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception{//鉴权配置http.authorizeHttpRequests(authorizeHttpRequests->authorizeHttpRequests//允许所有的OPTIONS请求.requestMatchers(HttpMethod.OPTIONS,"/**").permitAll()//放行swagger3.requestMatchers(HttpMethod.GET,"/v3/api-docs/**","/doc.html","/webjars/**").permitAll().anyRequest().authenticated());//认证配置http.formLogin().successHandler(simpleAuthenticationSuccessHandler) //认证成功后的处理器.failureHandler(simpleAuthenticationFailureHandler) //认证失败后的处理器.permitAll();//这句配置很重要，新手容易忘记。放开 login.html和dologin 的访问权//退出操作配置http.logout().logoutSuccessHandler(simpLogoutSuccessHandler);//将自定义的jwtFilter添加到Spring Security过滤器链的倒数第二个以前http.addFilterAfter(jwtFilter, UsernamePasswordAuthenticationFilter.class);//认证和鉴权异常配置http.exceptionHandling().authenticationEntryPoint(simpleAuthenticationEntryPoint) //认证异常处理器.accessDeniedHandler(simpleAccessDeniedHandler); //鉴权异常处理器//前后端项目中要禁用掉sessionhttp.sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS);//关闭crsf 跨域漏洞防御http.csrf(csrf-> csrf.disable());return http.build();}

http://www.ppmy.cn/embedded/119643.html

相关文章

[深度学习]卷积神经网络CNN

[深度学习]卷积神经网络CNN

1 图像基础知识 import numpy as np import matplotlib.pyplot as plt # 图像数据 #imgnp.zeros((200,200,3)) imgnp.full((200,200,3),255) # 可视化 plt.imshow(img) plt.show() # 图像读取 imgplt.imread(img.jpg) plt.imshow(img) plt.show() 2 CNN概述 卷积层convrelu池…
阅读更多...
商标名称注册查询，到底是查询什么！

商标名称注册查询，到底是查询什么！

在商标注册前是需要商标名称注册查询&#xff0c;那这个到底是查询什么&#xff0c;普推知产商标老杨发现&#xff0c;近日国家知产局发布《商标代理委托合同示范文本》征求意见稿&#xff0c;虽然是参考使用不具有强制性&#xff0c;里面对商标名称注册查询描述是申请前商标检…
阅读更多...
3. 轴指令（omron 机器自动化控制器）——＞MC_MoveVelocity

3. 轴指令（omron 机器自动化控制器）——＞MC_MoveVelocity

机器自动化控制器——第三章 轴指令 6 MC_MoveVelocity变量▶输入变量▶输出变量▶输入输出变量 功能说明▶指令详情▶时序图▶重启运动指令▶多重启动运动指令▶异常 动作示例▶动作示例▶梯形图▶结构文本(ST) MC_MoveVelocity 使用伺服驱动器的位置控制模式&#xff0c;进行…
阅读更多...
jenkins配置eureka、nacos发布优雅上下线服务

jenkins配置eureka、nacos发布优雅上下线服务

eureka发布期间优雅上下线 1、编写eureka下线脚本 vim biz_out_of_service-eureka.pyimport sys import requests#服务名&#xff0c;脚本第一个参数 APP_NAMEsys.argv[1] # 需要置为OUT_OF_SERVICE的服务实例的ID&#xff0c;脚本第二个参数 INSTANCE_IDsys.argv[2]# Eureka…
阅读更多...
大数据复习知识点1

大数据复习知识点1

1、HDFS和MapReduce的起源&#xff1a;HDFS起源于Google的GFS论文&#xff0c;它是为了解决大规模数据集的存储问题而设计的。而MapReduce则是Google为了解决大规模数据处理问题而提出的一种并行计算模型。 2、YARN的作用&#xff1a;YARN是Hadoop的资源管理器&#xff0c;它负…
阅读更多...
Java项目实战II基于Java+Spring Boot+MySQL的美容院管理系统设计与实现（源码+数据库+文档）

Java项目实战II基于Java+Spring Boot+MySQL的美容院管理系统设计与实现（源码+数据库+文档）

目录 一、前言 二、技术介绍 三、系统实现 四、文档参考 五、核心代码 六、源码获取 全栈码农以及毕业设计实战开发&#xff0c;CSDN平台Java领域新星创作者&#xff0c;专注于大学生项目实战开发、讲解和毕业答疑辅导。获取源码联系方式请查看文末 一、前言 在快速发展…
阅读更多...
SpringBoot项目请求不中断动态更新代码

SpringBoot项目请求不中断动态更新代码

在开发中&#xff0c;有时候不停机动态更新代码热部署是一项至关重要的功能&#xff0c;它可以在请求不中断的情况下下更新代码。这种方式不仅提高了开发效率&#xff0c;还能加速测试和调试过程。本文将详细介绍如何在 Spring Boot 项目在Linux系统中实现热部署&#xff0c;特…
阅读更多...
深度学习——D2(数据操作)

深度学习——D2(数据操作)

N维数组 创建数组 访问元素 一列: [ : , 1 ] 反向累积、正向累积&#xff08;自动求导&#xff09; 梯度 梯度&#xff08;Gradient&#xff09;是微积分中的一个重要概念&#xff0c;主要用于描述一个函数在某个区域内的变化情况。以下是对梯度的详细解释&#xff1a; 一…
阅读更多...
最新文章

Copyright @ 2022~2023