基于SpringBoot3从零配置SpringDoc
基于SpringBoot3从零配置SpringDoc
- 一、SpringFox
- 二、SpringDoc
- 三、Open API 规范
- 四、SpringBoot3配置Knife4j
- 1.官方参考文档
- 2.添加依赖
- 3.添加配置项
- 4.设置文档首页
- 5.编写控制器
- 6.文档展示
- 五、参考
一、SpringFox
- github SpringFox 已经停止更新了。
- SpringFox 对 SpringBoot3.0 不适配,要使用必须降低 SpringBoot的版本。
二、SpringDoc
-
SpringDoc,它可简化 API 文档的生成和维护,这些文档基于 OpenAPI 3 规范,适用于 Spring Boot 3.x 应用程序。Spring Boot 3.x 要求使用 springdoc-openapi version 2 及以上。
org.springdoc springdoc-openapi-starter-webmvc-ui 2.1.0
三、Open API 规范
- Open API 即开放 API,也称开放平台。 所谓的开放 API(OpenAPI)是服务型网站常见的一种应用,网站的服务商将自己的网站服务封装成一系列 API(Application Programming Interface,应用编程接口)开放出去,供第三方开发者使用,这种行为就叫做开放网站的 API,所开放的 API 就被称作 OpenAPI(开放 API )。
- OpenAPI 规范官方文档
- https://openapi.apifox.cn/
四、SpringBoot3配置Knife4j
- Knife4j 是一个集 Swagger2 和 OpenAPI3 为一体的增强解决方案。Knife4j 相当于是对 SpringDoc UI 优化的一个组件。
- Knife4j就是一个接口文档工具,可以看作是Swagger的升级版,但是界面比Swagger更好看,功能更丰富。
1.官方参考文档
- Knife4j官方网站
- https://doc.xiaominfo.com/
- 官方文档(快速开始)
- 快速开始
- 官方文档(Knife4j版本参考)
- Knife4j 版本参考
2.添加依赖
com.github.xiaoymin knife4j-openapi3-jakarta-spring-boot-starter 4.4.0
3.添加配置项
- 官方文档(详细配置):
- 3.1 增强模式
server.port: 8800 # 设置端口号 server: servlet: context-path: /test # 设置服务器的访问路径 springdoc: swagger-ui: path: /swagger-ui.html tags-sorter: alpha operations-sorter: alpha api-docs: path: /v3/api-docs group-configs: - group: test paths-to-match: '/**' # 生成文档所需的扫包路径,一般为启动类目录 packages-to-scan: com.gdb.test #knife4j 增强配置 knife4j: #是否启用增强设置 enable: true #开启生产环境屏蔽 production: false #是否启用登录认证 basic: enable: true username: admin password: 123456 setting: # 前端UI的个性化配置属性 language: zh_cn # 显示语言中文 enable-version: true enable-swagger-models: true # 是否显示界面中SwaggerModel功能 swagger-model-name: SwaggerModel2 # 重命名SwaggerModel名称,默认 enable-document-manage: true # 是否显示界面中"文档管理"功能
4.设置文档首页
import io.swagger.v3.oas.models.ExternalDocumentation; import io.swagger.v3.oas.models.OpenAPI; import io.swagger.v3.oas.models.info.Contact; import io.swagger.v3.oas.models.info.Info; import io.swagger.v3.oas.models.info.License; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; @Configuration public class Knife4jConfig { @Bean public OpenAPI myOpenAPI() { return new OpenAPI() // 接口文档标题 .info(new Info().title("程序员API") // 接口文档简介 .description("这是基于Knife4j OpenApi3的接口文档") .termsOfService("https://blog.csdn.net/weixin_65032328?type=blog") // 接口文档版本 .version("v1.0.0") // 接口文档协议 .license(new License() .name("许可协议") .url("https://blog.csdn.net/weixin_65032328?type=blog")) // 开发者联系方式 .contact(new Contact() .name("迷人的小宝") .email("dingbaogui8@gmail.com") .url("https://blog.csdn.net/weixin_65032328?type=blog"))) .externalDocs(new ExternalDocumentation() .description("小宝945博客") .url("https://blog.csdn.net/weixin_65032328?type=blog")); } }
5.编写控制器
import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.Parameter; import io.swagger.v3.oas.annotations.Parameters; import io.swagger.v3.oas.annotations.tags.Tag; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RestController; @Tag(name = "项目首页", description = "用户首先访问的页面") @RestController public class HelloController { @Parameters ({ //详细说明每一个参数 @Parameter(name = "name", description = "请求人姓名", required = true) }) @Operation (summary = "简短描述", description = "更详细的描述") @PostMapping("/calldingbao") public String hello(String name){ return name + "好啊,我是xiu宝哦!!!"; } }
import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.Parameter; import io.swagger.v3.oas.annotations.enums.ParameterIn; import io.swagger.v3.oas.annotations.media.Content; import io.swagger.v3.oas.annotations.responses.ApiResponse; import io.swagger.v3.oas.annotations.tags.Tag; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.PathVariable; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; @RestController @RequestMapping("/user") @Tag(name = "用户管理", description = "用户数据增删改查") public class UserController { @Operation( summary = "根据ID,查询用户", parameters = { @Parameter(name = "id", description = "用户的唯一标识 id", required = true, in = ParameterIn.PATH) }, responses = { @ApiResponse(responseCode = "200", description = "成功", content = @Content(mediaType = "application/json")), @ApiResponse(responseCode = "400", description = "错误", content = @Content(mediaType = "application/json")) } ) @GetMapping("/{id}") public Integer getUserById(@PathVariable int id) { return id; } }
6.文档展示
- 3.1 增强模式
- 官方文档(详细配置):
- Knife4j 版本参考
- Knife4j官方网站
- https://openapi.apifox.cn/
-
文章版权声明:除非注明,否则均为主机测评原创文章,转载或复制请以超链接形式并注明出处。