Swagger3 使用详解

2024-02-28 17:12
文章标签 使用 详解 swagger3

本文主要是介绍Swagger3 使用详解，希望对大家解决编程问题提供一定的参考价值，需要的开发者们随着小编来一起学习吧！

Swagger3 使用详解

  • 一、简介
    • 1 引入依赖
    • 2 开启注解
    • 3 增加一个测试接口
    • 4 启动服务报错
    • 1.5 重新启动
    • 6 打开地址：http://localhost:8093/swagger-ui/index.html
  • 二、Swagger的注解
    • 1.注解@Api和@ApiOperation
    • 2.注解@ApiModel和@ApiModelProperty
    • 3.注解@ApiImplicitParams和@ApiImplicitParam
    • 4.注解@ApiResponses和ApiResponse
    • 5.注解@ApiIgnore
  • 三、Swagger的相关配置

一、简介

官方网站：https://swagger.io/
Swagger 是一个开源的 API 开发和文档框架，Swagger 旨在简化 RESTful API 的设计、开发、测试、文档化和消费过程。Swagger的出现节约了大量的后端人员对接接口的时间，通过Swagger可以快速定义接口文档，方便了前端后端的接口对接工作，废话不多说直接上用例。
这里使用的SpringBoot 是2.6.11 版本

1 引入依赖

<dependency><groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>3.0.0</version>
</dependency>

2 开启注解

启动类增加注解

@EnableSwagger2
// 或者使用下面的注解，也是可以的
@EnableOpenApi

3 增加一个测试接口

增加一个接口，方便看到Swagger帮我们生成的接口文档中的接口信息，如下：

package com.cheng.ebbing.message.controller;import com.cheng.ebbing.message.vo.UserVO;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;/*** @author pcc* @version 1.0.0* @description 测试接口*/
@RestController
public class TestController {@RequestMapping(value ="/test")public UserVO test(){return new UserVO("zhangsan","1234",1);}
}

4 启动服务报错

报错：Failed to start bean ‘documentationPluginsBootstrapper’; nested exception is java.lang.NullPointerException
原因可以参考这篇文章 https://blog.csdn.net/weixin_45131680/article/details/131580270，总结一句话就是SpringBoot2.6以上的版本整合Swagger2:3.0.0会碰到这个问题，根本原因是路径匹配模式不适配。解决方案有两个，他们的目的是为了更改路径匹配规则以适配Swagger2 的3.0 的版本。

  • 解决方案一：
    // 启动类增加了开启swagger注解的基础上增加以下注解
@EnableWebMvc
  • 解决方案二：
    配置文件增加以下配置：
    spring:mvc:pathmatch:matching-strategy: ant_path_matcher

1.5 重新启动

选择上面其中一个方案进行解决即可，然后重新启动就会正常了，如下：
在这里插入图片描述

6 打开地址：http://localhost:8093/swagger-ui/index.html

到这里swagger的入门集成就成功了，如果你没有设置项目的根路径，那么Swagger的地址就是这个了，如果设置了自行端口后增加根路径就行，打开后如下图：
在这里插入图片描述
界面里有四块信息是需要关注的。
左一：展示的信息支持自定义，可以用来标识文档的和服务的信息（第四部分进行详细介绍）
左二：接口展示，这里展示接口的详细信息，最常用的地方,可以看到上面定义的测试接口已经在这里了（第二部分详细介绍）
左三：这里展示我们再请求和响应中定义的实体信息，比如上面接口的UserVO就在这里（第二部分详细介绍）
右一：分组信息，一般用于多个微服务时对不同微服务进行分组，常用与和Gateway集成时对服务进行分组展示（第三部分详细介绍）

二、Swagger的注解

这里详细说下Swagger常用的注解，根据使用频率来进行先后说明。这里分为了五个部分来说，前四个部分都是分组来说的，每组注解基本都是一起使用的所以就放一起来说，也方便理解记忆。下面的前四组例子都将使用使用注解和不使用注解的方式来进行说明比对，以此来方便了解注解的具体的作用。

1.注解@Api和@ApiOperation

这是使用频率最高的一组注解了。@Api常用与接口类上，用以对当前的接口类做整体声明。@ApiOperation则用于接口方法上，用以描述具体的方法真。

  • @Api
    正使用时其实只需要为@Api声明tags标签即可（其他的基本用不到，如果需要再阅读下注解的源码即可），value的值在源码描述中说是当tags不使用时会将其作为资源的描述，但是笔者试了没啥用，而且大家都是使用tags，直接使用tags标签即可。假如存在下面两个方法，他们的信息基本都是相同的，一个使用了@Api注解，一个没有使用：

    // 使用了 @Api注解的类
@Api(tags = "测试接口类1")
@RestController
public class TestController1 {@PostMapping("/test1Fun")public String test() {return "test1";}
}// 未使用@Api注解的类
@RestController
public class TestController2 {@PostMapping("/test2Fun")public String test() {return "test2";}
}

    下面一起看下他们在Swagger中的展示区别吧（注意重启生效）：
    在这里插入图片描述
    可以看到使用后多了汉字的描述，这样对于文档使用者来说也就更为有好了，这也就是tags属性的作用了，其他属性基本不咋使用。

  • @ApiOperation
    这个注解则是使用在接口方法上的，用以描述一个具体的接口，它支持的所有属性都是和RequestMapping对应的，因为他本来就是用来描述接口的和RequestMapping对应则是很好理解的。不过最常用的还是他的value属性，用以简介当前的接口。其他用以描述接口的信息一般不设置也是可以看到的，我们一般使用value属性简单描述接口的作用。
    下面是一组使用@ApiOperation和不使用的代码：

    
// 使用注解@ApiOperation
@ApiOperation("测试接口1-方法1")
@PostMapping("/test1Fun")
public String test() {return "test1";
}// 不使用注解@ApiOperation
@PostMapping("/test2Fun")
public String test() {return "test2";
}

    下面一起看下使用注解和不使用注解在Swagger中的区别：
    在这里插入图片描述

2.注解@ApiModel和@ApiModelProperty

这组注解是使用在实体上的，一般前后端参数交互时都是使用Json数据进行交互，Json交互时后端使用实体和注解@RequestBody来接收前端传递的参数，而这组注解则是用来描述实体的。实体既可以作为接收参数当然也可以作为返回参数。下面一起来看下。

  • @ApiModel
    被用于修饰实体类，实体类可用于接口入参和返参，一般只使用value属性即可。假设有如下两个实体信息，一个加了ApiModel一个没有加：

    // 使用了注解@ApiModel的注解
@Data
@ApiModel("用户实体1")
@AllArgsConstructor
@NoArgsConstructor
public class UserVO1 implements Serializable {private static final long serialVersionUID = 1L;private String username;private String password;Integer id;
}// 不使用注解@ApiModel
@Data
@AllArgsConstructor
@NoArgsConstructor
public class UserVO2 implements Serializable {private static final long serialVersionUID = 1L;private String username;private String password;Integer id;
}

    先看下使用了注解时的样子（不使用则显示类名）：
    在这里插入图片描述
    下面是不使用的样子：
    在这里插入图片描述
    此外在下面的位置也是可以看出区别的：
    在这里插入图片描述

  • @ApiModelProperty
    这个属性被用在实体的属性上，用来标识实体属性的含义，这个还是很有用的，因为不用他来标识的话有些字段是人无法知道具体代表的含义的。这个也是基本使用value即可，下面也是使用使用和不使用注解来比对下区别，这里就只贴使用注解的代码了

    @Data
@ApiModel("用户实体1")
@AllArgsConstructor
@NoArgsConstructor
public class UserVO1 implements Serializable {private static final long serialVersionUID = 1L;@ApiModelProperty("用户名")private String username;@ApiModelProperty("用户密码")private String password;@ApiModelProperty("用户ID")Integer id;
}

    下面是在swagger文章中看到的区别：
    在这里插入图片描述

3.注解@ApiImplicitParams和@ApiImplicitParam

上面一组注解被用于标识使用实体接收和返回的数据对象，那么如果接受的数据不是json呢，则需要别的注解来处理了，这一组注解就可以实现这个功能。

  • 参数传递大致有以下几种
    • 1.使用body传递json，后端使用注解RequestBody来接收
    • 2.使用body传递form-data，后端使用注解RequestParam接收（文件除外）
    • 3.使用body传递x-www-form-urlencoded，后端使用注解RequestParam接收
    • 4.使用path传参（restful），后端使用注解PathVariable来接收
    • 5.使用query传参，即url传参，后端使用注解RequestParam接收
    • 6.使用Cookie传参，后端使用注解CookieValue接收

上面列举了集中数据的传递方式，可以看到除了Json进行传递，还有一些其他的数据传递，此时@ApiModel这组注解就无法满足我们的需要了，那就只能使用@ApiImplicitParams和@ApiImplicitParam。上面的这些数据传递（除了json）都会在接口方法有参数进行映射。所以使用这组注解就都可以进行声明。这组注解和上面还有一点区别就是必须同时使用。

这里使用query传参进行说明吧。假设有如下接口代码：

@ApiOperation("测试接口1-方法1")
@PostMapping("/test1Fun")
public UserVO1 test(@RequestParam("name")String name) {return new UserVO1("用户1","1234",10);
}

不使用注解时，swagger展示如下：
在这里插入图片描述
当添加了如下注解以后：

@ApiOperation("测试接口1-方法1")
@PostMapping("/test1Fun")
@ApiImplicitParams({@ApiImplicitParam(name = "name",value = "用户名",required = true,paramType = "query",dataType = "String",dataTypeClass = String.class)
})
public UserVO1 test(@RequestParam("name")String name) {return new UserVO1("用户1","1234",10);
}

swagger中展示如下：
在这里插入图片描述
注意：可以看到只是多了在注解ApiImplicitParam中描述的value其他都是相同的，所以说其实使用这组注解时只需要关注ApiImplicitParam他的value就行了。不过需要注意的是这里还是用了注解@RequestParam，swagger文档中的required和query是这个注解赋予的，如果没有这个注解swagger文档是不会有对应提示的。还有一点，若是使用ApiImplicitParam的dataType则一定要使用dataTypeClass不然会一直提示warn日志
在这里插入图片描述

4.注解@ApiResponses和ApiResponse

上一组注解时用来描述除了实体以外的入参的，这个注解从字面看就知道是跟返回信息有关的，先看下不加这个注解时的接口的返回在swagger中的展示：
在这里插入图片描述
然后我们为接口增加这组注解，如下：

    @ApiOperation("测试接口1-方法1")@PostMapping("/test1Fun")@ApiResponses({@ApiResponse(code = 200, message = "成功", response = UserVO1.class,reference = "UserVO1"),@ApiResponse(code = 400, message = "失败",response = UserVO1.class,reference = "UserVO1")})public UserVO1 test(@RequestParam("name")String name) {return new UserVO1("用户1","1234",10);}

下面是使用注解后的swagger文档展示：
在这里插入图片描述
可以看到真正有作用的是code和message，所以如果需要使用就使用这两个即可，不过一把不使用这组注解，因为后端服务一般不会抛出http的异常码，而是通过实体的错误码来标识响应信息。

5.注解@ApiIgnore

这个注解也比较简单，可以使用在类或者方法上都是可以的，用以将其排除，排除后swagger不会将其加入文档。
假如有如下代码：

    @ApiIgnore@ApiOperation("测试接口1-方法1")@PostMapping("/test1Fun")@ApiResponses({@ApiResponse(code = 200, message = "成功", response = UserVO1.class,reference = "UserVO1"),@ApiResponse(code = 400, message = "失败",response = UserVO1.class,reference = "UserVO1")})public UserVO1 test(@RequestParam("name")String name) {return new UserVO1("用户1","1234",10);}

因为加了该注解，我们再swagger中是看不到的：
在这里插入图片描述

三、Swagger的相关配置

其实不添加任何配置不影响使用，但知道配置方便我们更好地针对自己的特别需求进行定制化。所以配置还是需要进行了解和熟悉的。比如生产上是不推荐打开swagger的，因为有很大的安全隐患。下面一起说下，注意这些配置信息都需要放在配置文件，这里为了方便都直接写死了。

package com.cheng.ebbing.message;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;/*** @author pcc* @version 1.0.0* @description swagger3配置类*/
@EnableWebMvc // 适配springboot2.6和swagger3
@EnableOpenApi // 开启swagger3
@Configuration
public class config {@Beanpublic Docket  createRestApi(){return new Docket(DocumentationType.OAS_30).enable(true) // 开启swagger，生产建议关闭.apiInfo(apiInfo()) // 配置文档的基础信息.groupName("这是分组名")// 不设置默认都是default，单个服务可以不使用分组，如果想要多个分组再来个Docket设置组名即可.select() // 开始配置路径相关信息// 扫描固定包，其他包下的信息不回出现在swagger.apis(RequestHandlerSelectors.basePackage("com.cheng.ebbing"))// 扫描所有有注解的api，用这种方式更灵活,也可以扫描指定的接口,支持通配符.paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {// 配置文档的基础信息，例如标题、描述等return new ApiInfoBuilder().title("这是title").description("这是description").license("这是license").licenseUrl("这是licenseUrl").termsOfServiceUrl("这是termsOfServiceUrl").contact(new Contact("concat-name","concat-url","concat-email")).version("版本1.0.0").build();}
}

增加完配置信息以后，swagger文档展示如下：
在这里插入图片描述
这些配置信息，注意不要直接写死，而应该从配置文件获取，这里直接写死只是为了演示使用，swagger只是项目辅助的小框架就只说到这里了。

这篇关于Swagger3 使用详解的文章就介绍到这儿，希望我们推荐的文章对编程师们有所帮助！

原文地址:
本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若转载，请注明出处：http://www.chinasem.cn/article/756093。

相关文章

windows和Linux安装Jmeter与简单使用方式

windows和Linux安装Jmeter与简单使用方式

《windows和Linux安装Jmeter与简单使用方式》：本文主要介绍windows和Linux安装Jmeter与简单使用方式,具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地... 目录Windows和linux安装Jmeter与简单使用一、下载安装包二、JDK安装1.windows设
阅读更多...
Spring 缓存在项目中的使用详解

Spring 缓存在项目中的使用详解

《Spring缓存在项目中的使用详解》Spring缓存机制,Cache接口为缓存的组件规范定义,包扩缓存的各种操作（添加缓存、删除缓存、修改缓存等）,本文给大家介绍Spring缓存在项目中的使用... 目录1.Spring 缓存机制介绍2.Spring 缓存用到的概念Ⅰ.两个接口Ⅱ.三个注解(方法层次)Ⅲ.
阅读更多...
Spring Boot 整合 Redis 实现数据缓存案例详解

Spring Boot 整合 Redis 实现数据缓存案例详解

《SpringBoot整合Redis实现数据缓存案例详解》Springboot缓存,默认使用的是ConcurrentMap的方式来实现的,然而我们在项目中并不会这么使用,本文介绍SpringB... 目录1.添加 Maven 依赖2.配置Redis属性3.创建 redisCacheManager4.使用Sp
阅读更多...
Spring Cache注解@Cacheable的九个属性详解

Spring Cache注解@Cacheable的九个属性详解

《SpringCache注解@Cacheable的九个属性详解》在@Cacheable注解的使用中,共有9个属性供我们来使用,这9个属性分别是：value、cacheNames、key、key... 目录1.value/cacheNames 属性2.key属性3.keyGeneratjavascriptor
阅读更多...
PyTorch中cdist和sum函数使用示例详解

PyTorch中cdist和sum函数使用示例详解

《PyTorch中cdist和sum函数使用示例详解》torch.cdist是PyTorch中用于计算**两个张量之间的成对距离（pairwisedistance）**的函数,常用于点云处理、图神经网... 目录基本语法输出示例1. 简单的 2D 欧几里得距离2. 批量形式（3D Tensor）3. 使用不
阅读更多...
Python模拟串口通信的示例详解

Python模拟串口通信的示例详解

《Python模拟串口通信的示例详解》pySerial是Python中用于操作串口的第三方模块,它支持Windows、Linux、OSX、BSD等多个平台,下面我们就来看看Python如何使用pySe... 目录1.win 下载虚www.chinasem.cn拟串口2、确定串口号3、配置串口4、串口通信示例5
阅读更多...
Nginx 413修改上传文件大小限制的方法详解

Nginx 413修改上传文件大小限制的方法详解

《Nginx413修改上传文件大小限制的方法详解》在使用Nginx作为Web服务器时,有时会遇到客户端尝试上传大文件时返回​​413RequestEntityTooLarge​​... 目录1. 理解 ​​413 Request Entity Too Large​​ 错误2. 修改 Nginx 配置2.1
阅读更多...
C#使用MQTTnet实现服务端与客户端的通讯的示例

C#使用MQTTnet实现服务端与客户端的通讯的示例

《C#使用MQTTnet实现服务端与客户端的通讯的示例》本文主要介绍了C#使用MQTTnet实现服务端与客户端的通讯的示例,包括协议特性、连接管理、QoS机制和安全策略,具有一定的参考价值,感兴趣的可... 目录一、MQTT 协议简介二、MQTT 协议核心特性三、MQTTNET 库的核心功能四、服务端（BR
阅读更多...
springboot项目redis缓存异常实战案例详解(提供解决方案)

springboot项目redis缓存异常实战案例详解(提供解决方案)

《springboot项目redis缓存异常实战案例详解(提供解决方案)》redis基本上是高并发场景上会用到的一个高性能的key-value数据库,属于nosql类型,一般用作于缓存,一般是结合数据... 目录缓存异常实践案例缓存穿透问题缓存击穿问题（其中也解决了穿透问题）完整代码缓存异常实践案例Red
阅读更多...
使用@Cacheable注解Redis时Redis宕机或其他原因连不上继续调用原方法的解决方案

使用@Cacheable注解Redis时Redis宕机或其他原因连不上继续调用原方法的解决方案

《使用@Cacheable注解Redis时Redis宕机或其他原因连不上继续调用原方法的解决方案》在SpringBoot应用中,我们经常使用​​@Cacheable​​注解来缓存数据,以提高应用的性能... 目录@Cacheable注解Redis时，Redis宕机或其他原因连不上，继续调用原方法的解决方案1
阅读更多...

Copyright China编程 23002807@qq.com

沪ICP备2023033072号-2