脚本之家 服务器常用软件
快捷导航
您的位置：首页 → 软件编程 → java → SpringBoot集成Swagger2

SpringBoot中集成Swagger2及简单实用

 更新时间：2023年06月10日 10:11:47   作者：秋天code  
使用Swagger你只需要按照它的规范去定义接口及接口相关的信息，再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，以及在线接口调试页面等等，这篇文章主要介绍了SpringBoot中集成Swagger2,需要的朋友可以参考下

介绍

Swagger是非常流行的API框架，能够自动生成RESTFul 风格的API文档，还可以在线测试后台接口。
使用Swagger你只需要按照它的规范去定义接口及接口相关的信息，再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，以及在线接口调试页面等等。
前后端分离的开发模式下，前端通过后端的API文档来进行开发和联调，效率更高。
Swagger就是帮助后端生成API文档的工具

简单使用

在SpringBoot中集成Swagger2，（等会说一个更简单的用法）。

引入依赖

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

配置类

@Configuration
@EnableSwagger2
public class Swagger2Config {
    /**
     * 将负责生成摘要的Bean提供出去
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //是否开启 (true 开启  false隐藏。生产环境建议隐藏)
                //.enable(false)
                .select()
                //扫描的路径包,设置basePackage会将包下的所有被@Api标记类的所有方法作为api
                .apis(RequestHandlerSelectors.basePackage("com.liumingkai.controller"))
                //指定路径处理PathSelectors.any()代表所有的路径
                .paths(PathSelectors.any())
                .build();
    }
    /**
     * 用来设置文档元信息
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //设置文档标题(API名称)
                .title("SpringBoot中使用Swagger2接口规范")
                //文档描述
                .description("接口说明")
                //版本号
                .version("1.0.0")
                .build();
    }
}

使用
因为Swagger帮助我们生成RestFul风格的文档，所以被修饰的接口方法必须是类似于@GetMapping、@PostMapping、@DeleteMapping，不能是一个笼统的@RequestMapping
下面会有详细的常用注解说明，此处只是想要来快速看一下效果

@RestController
@RequestMapping("/user")
@Api(value = "测试接口", tags = "用户登录接口")
public class LoginController {
    @PostMapping("/login")
    @ApiOperation(value = "登录", tags = "登录接口")
    public String login(String username, String password){
        return "登录成功"+username+password;
    }
    @PostMapping("/logout")
    @ApiOperation(value="退出登录",tags = "退出登录")
    public String logout(String username){
        return "退出登录成功";
    }
}

接下来访问http://ip:port/swagger-ui.html，会看到

SpringBoot版本与Swagger版本的冲突问题

如果你访问Swagger的文档地址后，发现是404，无法访问，那么大概是SpringBoot的版本问题

注意：
如果你的SpringBoot是2.6.x及更高，那么与Swagger2是不兼容的，因为SpringMVC的处理映射匹配的方式发生了变化。
需要在SpringBoot的配置文件中通过添加配置来使springboot2.6.x以后的版本来适配Swagger2
不要试图通过@EnableWebMvc来解决，同样会导致404

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

常用注解

Swagger的核心就是我们常用的这几个注解

@Api

一般用来标注在Controller上，注意此Controller要是一个RestController。

注解说明
@Api一般用在Controller类上，Swagger会扫描被此注解标注的类，并生成一个文档分类
@ApiOperation用在接口方法上，对该接口方法进行描述
@ApiModel用在实体类上，为此实体类生成说明文档
@ApiParam用来接口参数上，用来对此请求参数做说明
@ApiModelProperty用来实体类中的属性上，对此属性做说明
@RestController
@RequestMapping("/user")
@Api(value = "测试接口", tags = "用户登录接口")
public class LoginController {
}

属性：

  • value ， 该接口模块的名称，没啥用，对于程序员来说起一个标识作用
  • tags，该接口模块在文档中的标签名，会在API文档中显示。
    • 如果未指定此模块的tags标签，那么就会使用Controller的类名作为tags名称
    • tags可以认为是一个分类，名称相同的内容，会被归为一个分类。
  • hidden，隐藏该模块，默认是false，不隐藏，隐藏后该模块不会出现在api文档中

@ApiOperation

次注解用在方法上，对该接口进行描述。

@RestController
@RequestMapping("/user")
@Api(value = "测试接口", tags = "用户登录接口")
public class LoginController {
    @PostMapping("/login")
    @ApiOperation(value = "登录", tags = "用户登录接口")
    public String login(String username, String password){
        return "登录成功"+username+password;
    }
    @PostMapping("/logout")
    @ApiOperation(value="退出登录",tags = "用户登录接口")
    public String logout(String username){
        return "退出登录成功";
    }
}

属性：

  • value，该接口方法的名称，必填的属性，用来对接口标识作用
  • tags，用来指定该接口属于的标签，tags相同的接口方法，在文档中会属于同一个分类下
    • 一个接口方法可以属于多个分类
  • hidden，是否隐藏该接口，默认是false

@ApiParam

用在接口的参数上，用来对该参数进行修饰
属性：

  • value，标识作用
  • name，该参数的名称，如果省略该属性，则会以参数名来作为名称在文档中显示
  • required，是否必选，默认是false，此属性最常用
@RestController
@RequestMapping("/user")
@Api(value = "测试接口", tags = "用户登录接口")
public class LoginController {
    @PostMapping("/login")
    @ApiOperation(value = "登录", tags = "用户登录接口")
    public String login(@ApiParam(name="username", required = true) String username, @ApiParam(name="password",required = true) String password){
        return "登录成功"+username+password;
    }
    @PostMapping("/logout")
    @ApiOperation(value="退出登录",tags = "用户登录接口")
    public String logout(String username){
        return "退出登录成功";
    }
}

@ApiResponse

用在方法上，对接口的返回内容进行描述
常用属性：

  • code，响应的状态码
  • message，返回的描述信息
  • response，用来指定返回的实体类，也就是真正的响应数据
    @GetMapping("/detail/{username}")
    @ApiOperation("获取用户详情信息")
    @ApiResponse(code = 200,message = "查询成功",response = User.class)
    public User getDetail(@ApiParam(value = "要查询的用户名", required = true) @PathVariable("username") String username) {
        User user = new User();
        user.setAge(18);
        user.setUsername("zhagnsan");
        user.setPassword("123156");
        user.setSex("男");
        return user;
    }

@ApiResponses

如果返回的结果有多种，则可以使用@ApiResponses注解，此注解只有一个属性value，是一个@ApiResponse的数组。
其中包含多个@ApiResponse，每个@ApiResponse都是一种响应结果

    @GetMapping("/detail/{username}")
    @ApiOperation("获取用户详情信息")
    @ApiResponses({
            @ApiResponse(code = 200, message = "成功", response = User.class),
            @ApiResponse(code = 403, message = "你还没有权限")
    }
    )
    public User getDetail(@ApiParam(value = "要查询的用户名", required = true) @PathVariable("username") String username) {
        User user = new User();
        user.setAge(18);
        user.setUsername("zhagnsan");
        user.setPassword("123156");
        user.setSex("男");
        return user;
    }

@ApiModel

  • 用在实体类上，用来对此实体类进行描述。
  • 如果你的返回值类型或参数类型是实体类类型，那么Swagger就会使用@ApiModel对其进行描述

属性：

value，标识名，如果不填，则会以类名作为valuedescription，类的描述信息
实体类上标注了此类后，会将所有的属性进行描述

@ApiModel(value="用户实体类",description = "这是返回的实体类的描述信息")
@Data
public class User {
    private String username;
    private String password;
    private String sex;
    private Integer age;
}

一般都是直接@ApiModel注解，不用属性

@ApiProperty

如果需要对实体类中的属性进行单独的设置，那么就需要使用@ApiProperty属性了
常用属性：

  • value，标识
  • name，名称，在文档中的显示的名称
  • hidden，是否隐藏此属性
  • required，此属性是否必须
@ApiModel(value="用户实体类",description = "这是返回的实体类的描述信息")
@Data
public class User {
    @ApiModelProperty(value = "用户名",required = true)
    private String username;
    @ApiModelProperty(hidden = true)
    private String password;
    private String sex;
    private Integer age;
}

参考文档：
SpringBoot与Swagger2版本不兼容的问题！！
Failed to start bean ‘documentationPluginsBootstrapper‘； nested exception is java.lang.NullPointerEx_Shipley_Leo的博客-CSDN博客
Springboot ✚ Swagger各版本整理_swaager 版本_qq_33334411的博客-CSDN博客
swagger-ui.html页面无法打开解决方案_Alphathur的博客-CSDN博客

到此这篇关于SpringBoot中集成Swagger2的文章就介绍到这了,更多相关SpringBoot集成Swagger2内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

您可能感兴趣的文章:

相关文章

  • 剖析Java中的事件处理与异常处理机制

    剖析Java中的事件处理与异常处理机制

    这篇文章主要介绍了Java中的事件处理与异常处理机制,讲解Java是如何对事件或者异常作出响应以及定义异常的一些方法,需要的朋友可以参考下
    2016-01-01
  • Java之Maven工程打包jar

    Java之Maven工程打包jar

    Maven打包一般可以生成两种包一种是可以直接运行的包，一种是依赖包（只是编译包）。Maven默认打包时jar，如果需要修改其他类型，可以修改pom.xml。感兴趣的同学可以参考阅读
    2023-04-04
  • JavaWeb中struts2实现文件上传下载功能实例解析

    JavaWeb中struts2实现文件上传下载功能实例解析

    这篇文章主要介绍了JavaWeb中struts2文件上传下载功能的实现，在Web应用系统开发中，文件上传和下载功能是非常常用的功能,需要的朋友可以参考下
    2016-05-05
  • ArrayList详解和使用示例_动力节点Java学院整理

    ArrayList详解和使用示例_动力节点Java学院整理

    ArrayList 是一个数组队列，相当于 动态数组。与Java中的数组相比，它的容量能动态增长。接下来通过本文给大家介绍arraylist详解和使用示例代码，需要的的朋友一起学习吧
    2017-05-05
  • Java网络编程之入门篇

    Java网络编程之入门篇

    这篇文章主要介绍了Java网络编程入门，本文给大家介绍的非常详细，对大家的学习或工作具有一定的参考借鉴价值，需要的朋友可以参考下
    2021-09-09
  • mybatis 自定义实现拦截器插件Interceptor示例

    mybatis 自定义实现拦截器插件Interceptor示例

    这篇文章主要介绍了mybatis 自定义实现拦截器插件Interceptor，文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧
    2020-10-10
  • 解决idea update project 更新选项消失的问题

    解决idea update project 更新选项消失的问题

    这篇文章主要介绍了解决idea update project 更新选项消失的问题，具有很好的参考价值，希望对大家有所帮助。一起跟随小编过来看看吧
    2021-01-01
  • Java BigDecimal正确用法详解

    Java BigDecimal正确用法详解

    Java在java.math包中提供的API类BigDecimal，用来对超过16位有效位的数进行精确的运算。双精度浮点型变量double可以处理16位有效数，但在实际应用中，可能需要对更大或者更小的数进行运算和处理
    2022-10-10
  • SpringMvc接收参数方法总结(必看篇)

    SpringMvc接收参数方法总结(必看篇)

    下面小编就为大家带来一篇SpringMvc接收参数方法总结(必看篇)。小编觉得挺不错的，现在就分享给大家，也给大家做个参考。一起跟随小编过来看看吧
    2017-06-06
  • 基于Spring框架由ConditionalOnMissingBean注解引发的问题

    基于Spring框架由ConditionalOnMissingBean注解引发的问题

    这篇文章主要介绍了基于Spring框架由ConditionalOnMissingBean注解引发的问题,具有很好
    2023-11-11

最新评论