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

SpringBoot——整合Swagger

news 来源：原创 2024/9/20 12:12:45

Swagger

Swagger工具集

Swagger注解

项目总结

新建SpringBoot项目

pom.xml

Swagger2Config配置类

User实体类

UserController控制器

项目测试

添加用户

修改用户

查询用户

删除用户

Swagger

Swagger是一款基于RESTful接口的用于文档在线自动生成和功能测试的开发工具
为了减少前后端开发人员在开发期间的频繁沟通，可以使用Swagger提供的接口文档和线上接口进行前后端功能联调（前端代码和后端代码可以独立开发，后端开发人员不必立即理解前端代码的实现细节）
Swagger工具的功能：
辅助接口设计
辅助接口开发
生成接口文档
进行接口测试
Mock接口
接口管理
接口检测
Swagger可以整合到SpringBoot项目中并生成RESTful API文档，减少了开发者创建文档的工作量，同时将接口的说明内容整合在Java代码中，让维护文档和修改代码合为一体，可以让开发者在修改代码逻辑的同时方便地修改文档说明

Swagger工具集

Swagger-tools：提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger1.2文档转换成Swagger2.0文档等功能。
Swagger-core：用于Java/Scala的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF…）、Servlets和Play框架进行集成。
Swagger-js：用于JavaScript的Swagger实现。
Swagger-node-express：Swagger模块，用于node.js的Express web应用框架。
Swagger-ui：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。
Swagger-codegen：一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码

Swagger注解

@Configuration：表明这是一个配置类
@EnableSwagger2：开启Swagger2
@Api：放在类上，描述一个类的基本信息。
@ApiOperation：放在方法上，描述一个方法的基本信息
value：对方法作用的一个简短描述
notes：用来备注该方法的详细作用
@ApiImplicitParams：用在方法上，包含一组参数说明
@ApiImplicitParam：用来注解来给方法入参增加说明，一个请求能数
paramType：指方法参数的类型，可选值如下
path，参数获取方式：@PathVariable
query，参数获取方式：@RequestParam
header，参数获取方式：@RequestHeader
body
form
name：参数名称，和参数变量相对应
value：参数的描述信息
required：该字段是否必填
defaultValue：该字段的默认值
@ApiResponses：用于表示一组响应。
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：响应码
message：描述信息，例如“请求参数没填好”
response：抛出异常的类
@ApiModel：用对象来接收参数，描述一个Model的信息（一般用于在请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：用对象接收参数时，描述对象的一个字段
@ApiIgnore：不对某个接口生成文档
@ApiError ：发生错误返回的信息

项目总结

SpringBoot整合Swagger：

引入pom的相关依赖
在代码中加入相应的配置，新建config包，写入swaggerConfig配置类
在basePackage指定的路径下使用swagger（使用api注解，编写控制器类）
启动项目，浏览器打开http://ip:port/swagger-ui.html进行测试

新建SpringBoot项目

项目结构：

pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"><modelVersion>4.0.0</modelVersion><parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>2.3.12.RELEASE</version><relativePath/> <!-- lookup parent from repository --></parent><groupId>com.study</groupId><artifactId>springboot_swagger</artifactId><version>0.0.1-SNAPSHOT</version><name>springboot_swagger</name><description>Demo project for Spring Boot</description><properties><java.version>8</java.version></properties><dependencies><!--swagger--><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version></dependency><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency></dependencies><build><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin></plugins></build></project>

Swagger2Config配置类

package com.study.springboot_swagger.config;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.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration
@EnableSwagger2 //启用Swagger API文档
public class Swagger2Config {/*** 返回实例Docket(Swagger API摘要)* 在方法中指定扫描的控制器包路径,* 只有在此路径下的Controller类才会自动生成Swagger API文档* @return*/@Beanpublic Docket api(){return new Docket(DocumentationType.SWAGGER_2)  // 指定 Swagger 的版本为 2.apiInfo(apiInfo())  // 设定 API 文档的基本信息.select()  // 进入 API 选择模式.apis(RequestHandlerSelectors.basePackage("com.study.springboot_swagger.controller"))  // 指定扫描的包路径，Swagger 将扫描该包下的所有 Controller 类.paths(PathSelectors.any())  // 指定要包含的路径，PathSelectors.any() 表示包括所有路径.build();  // 完成 Docket 实例的构建}/*** 配置一些基本的显示信息,* 比如标题,描述,版本,服务条款,联系方式等* @return*/private ApiInfo apiInfo(){return new ApiInfoBuilder().title("swagger-api文档").description("swagger 文档 by liufu").version("1.0").build();}
}

User实体类

package com.study.springboot_swagger.entity;import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;@ApiModel(value = "用户实体类", description = "用户信息描述类")
@Data //getter,setter方法
public class User{@ApiModelProperty(value = "用户名")private String username;@ApiModelProperty(value = "用户地址")private String address;
}

UserController控制器

package com.study.springboot_swagger.controller;import com.study.springboot_swagger.entity.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;@RestController
@Api(tags = "用户数据接口")
public class UserController {@ApiOperation(value = "查询用户", notes = "根据id查询用户")@ApiImplicitParam(paramType = "path", name = "id", value = "用户id", required = true)@GetMapping("/user/{id}")public String getUserById(@PathVariable Integer id){return "/user/"+id;}@ApiResponses({@ApiResponse(code = 200, message = "删除成功!"),@ApiResponse(code = 500, message = "删除失败!")})@ApiOperation(value = "删除用户", notes = "通过id删除用户")@DeleteMapping("/user/{id}")public Integer deleteUserById(@PathVariable Integer id){return id;}@ApiOperation(value = "添加用户", notes = "添加一个用户,传入用户名和地址")@ApiImplicitParams({@ApiImplicitParam(paramType = "query", name = "username", value = "用户名", required = true, defaultValue = "sang"),@ApiImplicitParam(paramType = "query", name = "address", value = "用户地址", required = true, defaultValue = "shenzhen")})@PostMapping("/user")public String addUser(@RequestParam String username, @RequestParam String address){return username + ":" + address;}@ApiOperation(value = "修改用户", notes = "修改用户,传入用户信息")@PutMapping("/user")public String updateUser(@RequestBody User user){return user.toString();}@GetMapping("/ignore")@ApiIgnorepublic void ignoreMethod(){}
}