文章目录
- 1、什么是SpringDoc？
- 2、环境准备
- 3、添加依赖
- 4、配置SpringDoc
- 5、编写RestController
- 6、运行项目
- 7、自定义API文档
- 8、安全配置
- 9、结论
在现代Web开发中，API文档是一个至关重要的部分。它不仅可以帮助开发者理解和使用API，还可以提高开发效率，减少沟通成本。在Java生态系统中，SpringBoot是一个非常流行的框架，而SpringDoc则是一个用于生成OpenAPI规范的工具。本文将介绍如何在SpringBoot 3项目中整合SpringDoc，以实现在线接口文档的生成和展示。
1、什么是SpringDoc？
SpringDoc是一个自动生成API文档的工具，基于OpenAPI 3规范。它能够扫描SpringBoot项目中的注解，自动生成详尽的API文档，并提供一个Web界面供用户查看和测试API。SpringDoc取代了Swagger 2，提供了更现代化的解决方案，并支持最新的SpringBoot版本。
2、环境准备
在开始之前，我们需要确保以下环境已经搭建完毕：
JDK 11或以上版本Maven 3.6或以上版本- 一个
Spring Boot 3项目
3、添加依赖
首先，我们需要在pom.xml文件中添加SpringDoc的依赖。打开pom.xml文件，并在dependencies标签中添加以下内容：
<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.6.0</version>
</dependency>
4、配置SpringDoc
SpringDoc几乎不需要额外的配置，添加依赖后，它会自动扫描项目中的Controller并生成相应的API文档。不过，我们可以在application.properties或application.yml中进行一些基本的配置。
在application.properties中添加以下配置：
springdoc.api-docs.path=/api-docs
springdoc.swagger-ui.path=/swagger-ui.html
这些配置指定了API文档和Swagger UI界面的访问路径。
5、编写RestController
接下来，我们编写一个简单的RestController(不能是Controller)来演示SpringDoc的功能。创建一个名为UserController的类，并添加以下代码：
package com.example.demo.controller;import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestParam;