Spring Boot中如何使用Swagger详解
Swagger 简介
Swagger 是一个方便 API 开发的框架,它有以下优点:
- 自动生成在线文档,后端开发人员的改动可以立即反映到在线文档,并且不用单独编写接口文档,减轻了开发负担
- 支持通过 Swagger 页面直接调试接口,方便前端开发人员进行测试
配置 Swagger
Swagger 目前有 2.x 和 3.x 两个主流版本,配置略有不同。
添加依赖
首先去 Maven 仓库中搜索 springfox 查找依赖的坐标,Swagger 是遵循 OpenAPI 规范的技术,而 springfox 是该技术的一种实现,所以这里要搜 springfox 而不是 swagger。
对于 Swagger 2.x,需要在 pom.xml 中添加两项配置:
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
对于 Swagger 3.x,简化了配置项,只需要在 pom.xml 中添加一项配置:
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency>
为项目开启 Swagger
对于 Swagger 2.x,使用 @EnableSwagger2 注解开启 Swagger 功能。
@EnableSwagger2 @SpringBootApplication public class SwaggerApplication { ... }
对于 Swagger 3.x,使用 @EnableOpenApi 注解开启 Swagger 功能。
@EnableOpenApi @SpringBootApplication public class SwaggerApplication { ... }
创建 SwaggerConfig 配置类
- 对于 Swagger 2.x,实例化 Docket 的时候,需要传入 DocumentationType.SWAGGER_2。
- 对于 Swagger 3.x,实例化 Docket 的时候,需要传入 DocumentationType.OAS_30。
下面是一份配置模板:
import org.springframework.beans.factory.annotation.Value; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.*; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; @Configuration public class SwaggerConfig { @Value("${spring.profiles.active:NA}") private String active; @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) // OAS_30 .enable("dev".equals(active)) // 仅在开发环境开启Swagger .apiInfo(apiInfo()) .host("http://www.example.com") // Base URL .select() .apis(RequestHandlerSelectors.basePackage("com.example.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("API文档") .description("这是描述信息") .contact(new Contact("张三", null, null)) .version("1.0") .build(); } }
访问 Swagger 前端页面
- 对于 Swagger 2.x,访问 http://localhost:8080/swagger-ui.html
- 对于 Swagger 3.x,访问 http://localhost:8080/swagger-ui/
控制器相关注解
@Api:将一个类标记为 Swagger 资源,一般放在 Controller 类上面,通过 tags 指定描述信息,比如 @Api(tags="用户管理")。
@ApiOperation:本注解放在 Controller 方法上面,描述该方法的作用。
@ApiParam:本注解放在 Controller 方法的形参前面,可以描述参数的作用,比如 @ApiParam("用户名") String username。可以使用 value 指定描述信息,通过 required = true 指定必需传递该参数。
package com.example.swagger.controller; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiParam; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; @Api(tags = "Hello控制器") @RestController public class HelloController { @ApiOperation("展示欢迎信息") @GetMapping("/hello") public String hello(@ApiParam("名字") String name) { return "hello, " + name; } }
实体相关注解
- @ApiModel:一般放在实体类上面。可以通过 value 指定别名,不指定时默认为类名。还可以通过 description 指定详细的描述信息。比如 @ApiModel("用户") 就将显示 用户 而不是 User。
![](cdn.jsdelivr.net/gh/jpch89/P… 在 Spring Boot 中使用 Swagger 00.png)
如果仅仅想指定描述,而不改变原始类名显示,可以写成 @ApiModel(description = "用户")。
- @ApiModelProperty:一般放在实体类的成员变量上面,通过 value 指定描述信息,example 指定示例数据,required = true 指定该参数是必需的,hidden = true 用于隐藏该字段,不会在 API 文档中显示。
package com.example.swagger.pojo; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import lombok.Data; @Data @ApiModel(description = "用户") public class User { @ApiModelProperty("用户名") private String username; @ApiModelProperty("密码") private String password; @ApiModelProperty(value = "年龄", example = "18", required = true) private int age; @ApiModelProperty(hidden = true) private double money; }
总结
到此这篇关于Spring Boot中如何使用Swagger的文章就介绍到这了,更多相关SpringBoot使用Swagger内容请搜索猪先飞以前的文章或继续浏览下面的相关文章希望大家以后多多支持猪先飞!
相关文章
解决springboot使用logback日志出现LOG_PATH_IS_UNDEFINED文件夹的问题
这篇文章主要介绍了解决springboot使用logback日志出现LOG_PATH_IS_UNDEFINED文件夹的问题,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧...2021-04-28- 这篇文章主要为大家详细介绍了SpringBoot实现excel文件生成和下载,文中示例代码介绍的非常详细,具有一定的参考价值,感兴趣的小伙伴们可以参考一下...2021-02-09
- 这篇文章主要介绍了Swagger中@ApiIgnore注解的使用,具有很好的参考价值,希望对大家有所帮助。如有错误或未考虑完全的地方,望不吝赐教...2021-10-21
- 这篇文章主要介绍了详解springBoot启动时找不到或无法加载主类解决办法,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧...2020-09-16
- 这篇文章主要介绍了SpringBoot集成Redis实现消息队列的方法,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧...2021-02-10
- 这篇文章主要介绍了解决Springboot get请求是参数过长的情况,具有很好的参考价值,希望对大家有所帮助。一起跟随小编过来看看吧...2020-09-17
Spring Boot项目@RestController使用重定向redirect方式
这篇文章主要介绍了Spring Boot项目@RestController使用重定向redirect方式,具有很好的参考价值,希望对大家有所帮助。如有错误或未考虑完全的地方,望不吝赐教...2021-09-02- 这篇文章主要介绍了Springboot+TCP监听服务器搭建过程,本文通过图文并茂的形式给大家介绍的非常详细,对大家的学习或工作具有一定的参考借鉴价值,需要的朋友可以参考下...2020-10-28
- 这篇文章主要介绍了springBoot 项目排除数据库启动方式,具有很好的参考价值,希望对大家有所帮助。如有错误或未考虑完全的地方,望不吝赐教...2021-09-10
详解SpringBoot之访问静态资源(webapp...)
这篇文章主要介绍了详解SpringBoot之访问静态资源(webapp...),文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧...2020-09-14- 这篇文章主要介绍了SpringBoot接口接收json参数解析,具有很好的参考价值,希望对大家有所帮助。如有错误或未考虑完全的地方,望不吝赐教...2021-10-19
springboot中使用@Transactional注解事物不生效的坑
这篇文章主要介绍了springboot中使用@Transactional注解事物不生效的原因,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧...2021-01-26- 这篇文章主要介绍了springboot多模块包扫描问题的解决方法,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧...2020-09-16
Springboot+MDC+traceId日志中打印唯一traceId
本文主要介绍了Springboot+MDC+traceId日志中打印唯一traceId,文中通过示例代码介绍的非常详细,具有一定的参考价值,感兴趣的小伙伴们可以参考一下...2021-10-17Springboot mybatis plus druid多数据源解决方案 dynamic-datasource的使用详解
这篇文章主要介绍了Springboot mybatis plus druid多数据源解决方案 dynamic-datasource的使用,本文给大家介绍的非常详细,对大家的学习或工作具有一定的参考借鉴价值,需要的朋友可以参考下...2020-11-18- 这篇文章主要介绍了Springboot实现多线程注入bean的工具类操作,具有很好的参考价值,希望对大家有所帮助。一起跟随小编过来看看吧...2020-08-27
SpringBoot部署到Linux读取resources下的文件及遇到的坑
本文主要给大家介绍SpringBoot部署到Linux读取resources下的文件,在平时业务开发过程中,很多朋友在获取到文件内容乱码或者文件读取不到的问题,今天给大家分享小编遇到的坑及处理方案,感兴趣的朋友跟随小编一起看看吧...2021-06-21- 这篇文章主要介绍了springboot中nacos动态路由的配置方式,具有很好的参考价值,希望对大家有所帮助。如有错误或未考虑完全的地方,望不吝赐教...2021-09-11
SpringBoot高版本修改为低版本时测试类报错的解决方案
这篇文章主要介绍了SpringBoot高版本修改为低版本时测试类报错的解决方案,具有很好的参考价值,希望对大家有所帮助。如有错误或未考虑完全的地方,望不吝赐教...2021-09-18解决Springboot整合shiro时静态资源被拦截的问题
这篇文章主要介绍了解决Springboot整合shiro时静态资源被拦截的问题,具有很好的参考价值,希望对大家有所帮助。一起跟随小编过来看看吧...2021-01-26