拥抱 OpenAPI 3:springdoc-openapi 食用指南
2024-09-01 17:15:38
概述
使用 springdoc-openapi 可以快速为 springboot 项目生成规范的 API 文档,具体使用步骤如下:
依赖配置
在 pom.xml
加入内容,即可开始使用:
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.6.9</version>
</dependency>
然后在 Config 中配置基本的描述信息,如下:
@Configuration
public class OpenApiConfig {
@Bean
public OpenAPI springOpenAPI() {
return new OpenAPI()
.info(new Info()
.title("SpringDoc API Test")
.description("SpringDoc Simple Application Test")
.version("0.0.1"));
}
}
接下来在 Controller 中使用注解标记文本,如下:
@RestController(value = "/clients")
@Tag(name = "/clients")
public class ClientsRestController {
@Operation(summary = "This method is used to get the clients.")
@GetMapping
public List<String> getClients() {
return Arrays.asList("First Client", "Second Client");
}
}
最后 Application.java
启动应用后,输入默认地址:http://localhost:8081/swagger-ui/index.html
即可看到文档:
在地址 http://localhost:8081/v3/api-docs
目录中,openAPI 3.0.1 文件,格式如下:
总结
很多从 swagger 2 过来的用户可能会好奇,为什么不使用 springfox 库来生成 API,我在这里简单总结一下
推荐使用 springdoc-openapi 的理由如下:
- springdoc-openapi 是 spring 官方出品,与 springboot 兼容更好(springfox 兼容有坑)
- springdoc-openapi 社区更活跃,springfox 已经 2 年没更新了
- springdoc-openapi 的注解更接近 OpenAPI 3 规范
综上所述,我个人还是更加推荐使用 springdoc-openapi 来自动化你项目的 API 文档
最新文章
- 帝国cms搜索表单用法
- WebApp基础01-设置读取assets目录下文件
- [LeetCode] Ugly Number
- managed_shared_memory.construct造成的性能损失
- 240. Search a 2D Matrix II
- 垃圾回收GC:.Net自己主动内存管理 上(一)内存分配
- C# Http以文件的形式上传文件
- Java 后台sql注入
- 【转】linux IO子系统和文件系统读写流程
- LeetCode 106. Construct Binary Tree from Inorder and Postorder Traversal (用中序和后序树遍历来建立二叉树)
- node使用buffer生成图片
- Spring基础系列--AOP织入逻辑跟踪
- 【手记】解决excel无法设置单元格颜色且界面怪异+桌面图标文字老有色块等问题
- Linq中left join之多表查询
- 作业要求20160901 从edu.cnblogs.com中抄过来的,备忘
- linux C宏定义 转
- hdu 6395 Sequence (简单矩乘)
- PHP:第一章——PHP中的魔术常量
- 我是怎么从安卓到php再成为前端开发工程师的
- [转]How to log queries using Entity Framework 7?