swagger
springboot 集成 Swagger在线接口文档
1、swagger简介
2、swagger的maven依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
</dependency>
3、swagger配置
Spring Boot 中对 Swagger 的配置非常方便,
新建一个配置类,
类上除了添加必要的@Configuration 注解外,
还需要添加@EnableOpenApi 注解
package com.li.conf;
import io.swagger.models.HttpMethod;
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.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;
@EnableOpenApi//启用OpenAPI(以前称为Swagger)自动生成的API文档。
@Configuration
public class Swagger3Config {
/**
* 创建API应用
* apiInfo() 增加API相关信息
* 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现,
* 本例采用指定扫描的包路径来定义指定要建立API的目录。
* swagger测试地址:http://localhost:8080/swagger-ui/index.html#/
* @return
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.OAS_30) // 使用Swagger3.0版本
.enable(true)// 是否关闭在线文档,生产环境关闭
.apiInfo(apiInfo()) // 指定构建api文档的详细信息的方法
.select() // 指定要生成api接口的包路径,这里把action作为包路径,生成controller中的所有接口
.apis(RequestHandlerSelectors.basePackage("com.yan.action"))
// .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))方法接口上添加了ApiOperation注解
.paths(PathSelectors.any()).build()
//针对应用的全局响应消息配置
// .globalResponses(HttpMethod.GET, getGlobalResponseMessage())
// .globalResponses(HttpMethod.POST, getGlobalResponseMessage())
;
}
/**
* 创建该API的基本信息(这些基本信息会展现在文档页面中)
* 访问地址:http://项目实际地址/swagger-ui.html
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("接口文档") //设置页面标题
.description("说明信息") //设置接口描述
.contact(new Contact("li", "http://baidu.com", "li@li.com")) //设置联系方式
.version("1.0") //设置版本
.build(); //构建
}
}
4、swagger的使用
Swagger中常用的注解,分别在实体类上、Controller 类上以及 Controller 中的方法上。
4.1 实体类注解
实体类的注解主要介有:@ApiModel 和@ApiModelProperty 注解。
- @ApiModel 注解用于实体类,表示对类进行说明,用于参数用实体类接收。
@ApiModel(value = "用户实体类")
public class User {}
- @ApiModelProperty 注解用于类中属性,表示对 model 属性的说明或者数据操作更改
public class User {
@ApiModelProperty(value = "用户唯一标识")
private Long id;
@ApiModelProperty(value = "用户姓名")
private String username;
@ApiModelProperty(value = "用户密码")
private String password;
}
User类:
@ApiModel(value = "用户实体类")
public class User {
@ApiModelProperty(value = "用户唯一标识")
private Long id;
@ApiModelProperty(value = "用户姓名")
private String username;
@ApiModelProperty(value = "用户密码")
private String password;
}
4.2 Controller类注解
Controller类注解主要介有:@Api、@ApiOperation、@ApiParam
- 1、@Api 注解用于类上,表示标识这个类是 swagger 的资源。
@RestController
@RequestMapping("/swagger")
@Api(value = "Swagger2 在线接口文档")
public class TestController{}
- 2、@ApiOperation 注解用于方法
public class TestController {
@GetMapping("/get/{id}")
@ApiOperation(value = "根据用户唯一标识获取用户信息",notes = "用户测试notes",tags = "角色管理")
public JsonResult<User> getUserInfo(Long id) {}
}
value:可以当作是接口的简称
notes:接口的描述
tags:可以额外定义接口组,比如这个接口外层已经有@Api(tags = "用户管理"),将接口划分到了“用户管理”中,但你可以额外的使用tags,例如tags = "角色管理"让角色管理中也有这个接口文档。
- 3、@ApiParam 注解用于参数上,用来标明参数信息。
public JsonResult<User> getUserInfo(@PathVariable @ApiParam(value = "用户唯一标识") Long id) {
// 模拟数据库中根据 id 获取 User 信息
User user = new User(id, "李骏瑞", "123456");
return new JsonResult(user);
}
Controller类
@RestController
@RequestMapping("/swagger")
@Api(value = "Swagger2 在线接口文档")
public class TestController {
@GetMapping("/get/{id}")
@ApiOperation(value = "根据用户唯一标识获取用户信息")
public JsonResult<User> getUserInfo(@PathVariable @ApiParam(value = "用户唯一标识") Long id) {
// 模拟数据库中根据 id 获取 User 信息
User user = new User(id, "李骏瑞", "123456");
return new JsonResult(user);
}
}
【推荐】编程新体验,更懂你的AI,立即体验豆包MarsCode编程助手
【推荐】凌霞软件回馈社区,博客园 & 1Panel & Halo 联合会员上线
【推荐】抖音旗下AI助手豆包,你的智能百科全书,全免费不限次数
【推荐】博客园社区专享云产品让利特惠,阿里云新客6.5折上折
【推荐】轻量又高性能的 SSH 工具 IShell:AI 加持,快人一步
· DeepSeek “源神”启动!「GitHub 热点速览」
· 微软正式发布.NET 10 Preview 1:开启下一代开发框架新篇章
· 我与微信审核的“相爱相杀”看个人小程序副业
· C# 集成 DeepSeek 模型实现 AI 私有化(本地部署与 API 调用教程)
· spring官宣接入deepseek,真的太香了~