SpringBoot2.0整合Api文档Swagger
ztj100 2025-05-08 08:09 58 浏览 0 评论
前言
最近在整理Github的仓库时,看到以前大学的时候写了个SpringBoot和Swagger的demo,想了一下最后决定写一篇文章,记录一下。
Swagger简介
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码,允许 API 来始终保持同步。Swagger 让部署管理和使用功能强大的 API 从未如此简单。
创建工程
SpringBoot的版本是2.0.8,Swagger的版本是2.9.2
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.0.8.RELEASE</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<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.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
Swagger的配置
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
//主要api配置机制初始化为swagger规范2.0
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.msr.demo.swagger.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
Contact contact = new Contact("msr", "www.baidu,com", "maisrcn@qq.com");
return new ApiInfoBuilder()
// 标题
.title("Spring Boot中使用Swagger2构建RESTful API")
// 描述信息
.description("rest api 文档构建利器")
//服务网址
.termsOfServiceUrl("http://localhost:8080")
//版本号
.version("1.0")
.contact(contact)
.build();
}
}
Controller控制层
Swagger主要是在控制层上使用,通过一些注解来为接口提供API文档。下述的代码中主要使用的注解为这两个@ApiOperation和 @ApiImplicitParam这两个,@ApiOperation注解来给API增加说明并通过@ApiImplicitParams注解来给参数增加说明
下面试一些Swagger的常用的注解,更详细的可以查看官方的文档。
- @Api:将类标记为Swagger资源
- @ApiImplicitParam:表示API操作中的单个参数
- @ApiImplicitParams:一个包装器,允许列出多个ApiImplicitParam对象
- @ApiModel:提供有关Swagger模型的其他信息,比如描述POJO对象
- @ApiModelProperty: 添加和操作模型属性的数据
- @ApiOperation: 描述针对特定路径的操作或通常是HTTP方法
- @ApiParam: 为操作参数添加其他元数据
- @ApiResponse: 描述操作的可能响应
- @ApiResponses: 一个包装器,允许列出多个ApiResponse对象
- @Authorization: 声明要在资源或操作上使用的授权方案
- @AuthorizationScope: 描述OAuth2授权范
- @ResponseHeader: 表示可以作为响应的一部分提供的标头。
- @ApiProperty: 描述POJO对象中的属性值
- @ApiError : 接口错误所返回的信息
- ...
@Slf4j
@Api(tags = "用户相关相关的API")
@RestController
public class UserController {
@ApiOperation(value = "获取用户信息",notes="添加用户信息")
@PostMapping("/user")
public String addUser(@RequestBody User user) {
log.info("POST请求,接收到参数:{}", user.toString());
return user.toString();
}
@ApiOperation(value = "更新用户", notes = "根据User对象更新用户")
@ApiImplicitParam(name = "user", value = "用户实体user", required = true, dataType = "User")
@PutMapping("/user")
public boolean updateUser(@RequestBody User user) {
log.info("UPDATE请求,请求参数:{}", user);
return true;
}
@ApiOperation(value = "删除用户", notes = "根据User对象删除用户")
@ApiImplicitParam(name = "user", value = "用户实体user", required = true, dataType = "User")
@DeleteMapping("/user")
public boolean deleteUser(@RequestBody User user) {
log.info("DELETE请求,请求参数:{}", user);
return true;
}
@ApiOperation(value = "获取用户列表", notes = "根据User对象查询用户信息")
@ApiImplicitParam(name = "user", value = "用户实体user", required = true, dataType = "User")
@GetMapping("/user")
public User findByUser(User user) {
log.info("GET请求,请求参数:{}", user);
return User.builder()
.id(1)
.age(18)
.name("小明")
.build();
}
}
实体类
@ApiModel("用户实体")
@Data
@NoArgsConstructor
@AllArgsConstructor
public class User implements Serializable {
@ApiModelProperty("用户ID")
private Integer id;
@ApiModelProperty("用户名")
private String name;
@ApiModelProperty("登录密码")
private String password;
@ApiModelProperty("年龄")
private Integer age;
}
启动类
@SpringBootApplication
public class SwaggerDemoApplication {
public static void main(String[] args) {
SpringApplication.run(SwaggerDemoApplication.class, args);
}
}
测试
启动程序,浏览器访问
http://localhost:8080/swagger-ui.html
点开UserController和Models可以看到在代码中的配置
选择要测试的接口,点击Try it out。输入参数,
总结
其实,Swagger的注解很多,当把一个API描述好之后,会发现方法上多了一堆的注解。对于我个人来说有点不舒服,感觉有点侵略性的感觉。对于API文档,目前有很多的项目,感觉用起来也不错。
作者:8aceSuper
链接:
https://juejin.cn/post/6977369983928139812
相关推荐
- 其实TensorFlow真的很水无非就这30篇熬夜练
-
好的!以下是TensorFlow需要掌握的核心内容,用列表形式呈现,简洁清晰(含表情符号,<300字):1.基础概念与环境TensorFlow架构(计算图、会话->EagerE...
- 交叉验证和超参数调整:如何优化你的机器学习模型
-
准确预测Fitbit的睡眠得分在本文的前两部分中,我获取了Fitbit的睡眠数据并对其进行预处理,将这些数据分为训练集、验证集和测试集,除此之外,我还训练了三种不同的机器学习模型并比较了它们的性能。在...
- 机器学习交叉验证全指南:原理、类型与实战技巧
-
机器学习模型常常需要大量数据,但它们如何与实时新数据协同工作也同样关键。交叉验证是一种通过将数据集分成若干部分、在部分数据上训练模型、在其余数据上测试模型的方法,用来检验模型的表现。这有助于发现过拟合...
- 深度学习中的类别激活热图可视化
-
作者:ValentinaAlto编译:ronghuaiyang导读使用Keras实现图像分类中的激活热图的可视化,帮助更有针对性...
- 超强,必会的机器学习评估指标
-
大侠幸会,在下全网同名[算法金]0基础转AI上岸,多个算法赛Top[日更万日,让更多人享受智能乐趣]构建机器学习模型的关键步骤是检查其性能,这是通过使用验证指标来完成的。选择正确的验证指...
- 机器学习入门教程-第六课:监督学习与非监督学习
-
1.回顾与引入上节课我们谈到了机器学习的一些实战技巧,比如如何处理数据、选择模型以及调整参数。今天,我们将更深入地探讨机器学习的两大类:监督学习和非监督学习。2.监督学习监督学习就像是有老师的教学...
- Python 模型部署不用愁!容器化实战,5 分钟搞定环境配置
-
你是不是也遇到过这种糟心事:花了好几天训练出的Python模型,在自己电脑上跑得顺顺当当,一放到服务器就各种报错。要么是Python版本不对,要么是依赖库冲突,折腾半天还是用不了。别再喊“我...
- 神经网络与传统统计方法的简单对比
-
传统的统计方法如...
- 自回归滞后模型进行多变量时间序列预测
-
下图显示了关于不同类型葡萄酒销量的月度多元时间序列。每种葡萄酒类型都是时间序列中的一个变量。假设要预测其中一个变量。比如,sparklingwine。如何建立一个模型来进行预测呢?一种常见的方...
- 苹果AI策略:慢哲学——科技行业的“长期主义”试金石
-
苹果AI策略的深度原创分析,结合技术伦理、商业逻辑与行业博弈,揭示其“慢哲学”背后的战略智慧:一、反常之举:AI狂潮中的“逆行者”当科技巨头深陷AI军备竞赛,苹果的克制显得格格不入:功能延期:App...
- 时间序列预测全攻略,6大模型代码实操
-
如果你对数据分析感兴趣,希望学习更多的方法论,希望听听经验分享,欢迎移步宝藏公众号...
你 发表评论:
欢迎- 一周热门
- 最近发表
- 标签列表
-
- idea eval reset (50)
- vue dispatch (70)
- update canceled (42)
- order by asc (53)
- spring gateway (67)
- 简单代码编程 贪吃蛇 (40)
- transforms.resize (33)
- redisson trylock (35)
- 卸载node (35)
- np.reshape (33)
- torch.arange (34)
- npm 源 (35)
- vue3 deep (35)
- win10 ssh (35)
- vue foreach (34)
- idea设置编码为utf8 (35)
- vue 数组添加元素 (34)
- std find (34)
- tablefield注解用途 (35)
- python str转json (34)
- java websocket客户端 (34)
- tensor.view (34)
- java jackson (34)
- vmware17pro最新密钥 (34)
- mysql单表最大数据量 (35)