当前位置：首页 > news >正文

SpringBoot配置Swagger

news 2026/6/7 11:49:19

一、Swagger介绍

1、什么是Swagger

定义
OpenAPI 规范：描述 RESTful API 的标准格式（JSON/YAML）
Swagger 工具集：围绕 OpenAPI 规范构建的工具集合

2、为什么使用 Swagger？

优势
标准化文档 - 统一的 API 描述格式
交互式测试 - 直接在浏览器测试 API
前后端协作 - 基于文档先行开发
代码自动生成 - 减少手写代码
API 管理 - 版本控制、权限管理

二、Swagger常用注解

通过注解可以控制生成的接口文档，使接口文档拥有更好的可读性，常用注解如下：

1、@Api

@Api用在类上，例如Controller，表示对类的说明

@Api(tags="员工管理")@RestController@RequestMapping("/admin/employee")@Slf4jpublicclassEmployeeController{

2、@ApiModel

@ApiModel用在类上，例如entity、DTO、VO，配合@APIModelProperty使用

@Data@Builder@NoArgsConstructor@AllArgsConstructor@ApiModel("员工信息")publicclassEmployeeimplementsSerializable{privatestaticfinallongserialVersionUID=1L;@ApiModelProperty("员工id")privateLongid;@ApiModelProperty("用户名")privateStringusername;privateStringname;privateStringpassword;privateStringphone;privateStringsex;privateStringidNumber;privateIntegerstatus;// @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")privateLocalDateTimecreateTime;// @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")privateLocalDateTimeupdateTime;privateLongcreateUser;privateLongupdateUser;}

3、@ApiModelProperty

@ApiModelProperty用在属性上，描述属性信息

@Data@Builder@NoArgsConstructor@AllArgsConstructor@ApiModel("员工信息")publicclassEmployeeimplementsSerializable{privatestaticfinallongserialVersionUID=1L;@ApiModelProperty("员工id")privateLongid;@ApiModelProperty("用户名")privateStringusername;privateStringname;privateStringpassword;privateStringphone;privateStringsex;privateStringidNumber;privateIntegerstatus;// @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")privateLocalDateTimecreateTime;// @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")privateLocalDateTimeupdateTime;privateLongcreateUser;privateLongupdateUser;}

4、@ApiOperation

@ApiOperation用在方法上，例如Controller的方法，说明方法的用途、作用

@PostMapping("/login") @ApiOperation("员工登录") public Result<EmployeeLoginVO>login(@RequestBody EmployeeLoginDTO employeeLoginDTO) { log.info("员工登录：{}", employeeLoginDTO); Employee employee = employeeService.login(employeeLoginDTO); //登录成功后，生成jwt令牌 Map<String,Object>claims = new HashMap<>(); claims.put(JwtClaimsConstant.EMP_ID, employee.getId()); String token = JwtUtil.createJWT( jwtProperties.getAdminSecretKey(), jwtProperties.getAdminTtl(), claims); EmployeeLoginVO employeeLoginVO = EmployeeLoginVO.builder() .id(employee.getId()) .userName(employee.getUsername()) .name(employee.getName()) .token(token) .build(); return Result.success(employeeLoginVO); }

三、SpringBoot中配置Swagge

rKnife4j 是为Java MVC框架集成Swagger生成Api文档的增强解决方案。

1、引入依赖

<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>3.0.2</version></dependency>

2、使用方式

1、导入 knife4j 的maven坐标

<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>3.0.2</version></dependency>

2、在配置类中加入 knife4j 相关配置

@Configuration@Slf4jpublicclassWebMvcConfigurationextendsWebMvcConfigurationSupport{/** * 通过knife4j生成接口文档 * @return */@BeanpublicDocketdocket(){ApiInfoapiInfo=newApiInfoBuilder().title("项目接口文档").version("2.0").description("苍穹外卖项目接口文档介绍").build();Docketdocket=newDocket(DocumentationType.SWAGGER_2).apiInfo(apiInfo).select().apis(RequestHandlerSelectors.basePackage("com.sky.controller")).paths(PathSelectors.any()).build();returndocket;}

3、设置静态资源映射，否则接口文档页面无法访问

protectedvoidaddResourceHandlers(ResourceHandlerRegistryregistry){registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");}