如何在spring boot项目中使用swagger生成api文档？1.添加依赖，在pom.xml中引入springdoc-openapi-ui的依赖；2.创建配置类，定义openapi对象，设置标题、版本、描述等基本信息；3.在controller中使用@operation、@parameter、@apiresponse等注解描述接口信息；4.启动应用后访问http://localhost:8080/swagger-ui.html查看文档。此外，还可以使用@tag分组接口，@schema描述结构，@requestbody、@pathvariable、@requestparam分别描述不同类型的参数。通过修改配置类可自定义文档全局信息，如联系人、license等。swagger基于openapi标准生成文档，其中springdoc-openapi-ui是openapi 3.0的实现。
Swagger能帮你自动生成漂亮的API文档，省时省力，让前后端协作更顺畅。
解决方案
- 添加Swagger依赖
在你的pom.xml文件中添加Swagger的依赖。这里我们使用springdoc-openapi-ui，它提供了更现代的Swagger UI体验。
立即学习“Java免费学习笔记（深入）”；
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.6.4</version>
</dependency>当然，你也可以选择传统的swagger2和swagger-ui，但springdoc-openapi-ui更推荐。
- 配置Swagger
创建一个Swagger配置类，例如SwaggerConfig.java。
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class SwaggerConfig {
@Bean
public OpenAPI customOpenAPI() {
return new OpenAPI()
.info(new Info()
.title("我的API文档")
.version("1.0")
.description("这个文档包含了所有可用的API接口。"));
}
}这个配置类定义了API文档的基本信息，比如标题、版本和描述。 @Configuration告诉Spring这是一个配置类，@Bean则告诉Spring这是一个需要被管理的Bean。
- 使用Swagger注解
在你的Controller类和方法上添加Swagger注解，例如@Operation、@Parameter、@ApiResponse等。
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/users")
public class UserController {
@GetMapping("/{id}")
@Operation(summary = "获取用户详情", description = "根据用户ID获取用户的信息。")
@ApiResponse(responseCode = "200", description = "成功获取用户")
@ApiResponse(responseCode = "404", description = "用户不存在")
public String getUser(@Parameter(description = "用户ID") @PathVariable Long id) {
// ...你的业务逻辑...
return "用户ID: " + id;
}
@PostMapping
@Operation(summary = "创建用户", description = "创建一个新的用户。")
@ApiResponse(responseCode = "201", description = "成功创建用户")
public String createUser(@RequestBody String user) {
// ...你的业务逻辑...
return "创建用户: " + user;
}
}@Operation用于描述API接口，@Parameter用于描述参数，@ApiResponse用于描述响应。 这些注解让Swagger知道如何生成文档。
- 访问Swagger UI
启动你的Spring Boot应用，然后在浏览器中访问http://localhost:8080/swagger-ui.html。 你会看到Swagger UI界面，其中包含了所有API接口的文档。 （注意，8080是你的应用端口，如果你的应用端口不是8080，请替换成你的实际端口。）
Swagger注解有哪些常用的？
除了上面用到的 @Operation、@Parameter、@ApiResponse，还有一些其他的Swagger注解也很有用：
-
@Tag: 用于给API接口分组。比如，你可以将所有用户相关的接口放在一个组里，将所有订单相关的接口放在另一个组里。 -
@Schema: 用于描述请求体或响应体的结构。 这对于复杂的JSON对象非常有用。 -
@RequestBody: 用于描述请求体。 它可以和@Schema一起使用，详细描述请求体的每个字段。 -
@PathVariable: 用于描述路径参数。 和@Parameter类似，但更明确地指出参数是路径的一部分。 -
@RequestParam: 用于描述查询参数。 和@Parameter类似，但更明确地指出参数是查询字符串的一部分。
Swagger文档如何自定义？
Swagger文档的自定义主要体现在两个方面：一是配置，二是注解。
配置方面：你可以通过修改
SwaggerConfig.java来定制API文档的全局信息，比如标题、版本、描述、联系人信息、License信息等等。你还可以配置API接口的排序方式、是否显示内部接口等等。注解方面：你可以通过使用不同的Swagger注解，详细描述API接口的各个方面。 比如，你可以使用
@Operation的tags属性给API接口分组，使用@Schema的example属性给请求体或响应体添加示例数据。
例如，你想给API文档添加一个联系人信息：
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class SwaggerConfig {
@Bean
public OpenAPI customOpenAPI() {
return new OpenAPI()
.info(new Info()
.title("我的API文档")
.version("1.0")
.description("这个文档包含了所有可用的API接口。")
.contact(new Contact()
.name("张三")
.email("zhangsan@example.com")
.url("http://example.com")));
}
}Swagger和OpenAPI有什么关系？
Swagger实际上是一套完整的API工具链，包括Swagger Editor（API设计工具）、Swagger UI（API文档展示工具）、Swagger Codegen（API代码生成工具）等等。而OpenAPI Specification（OAS）是一种用于描述RESTful API的标准格式。Swagger 2.0版本使用了Swagger Specification，而Swagger 3.0版本则改名为OpenAPI Specification。
简单来说，OpenAPI是标准，Swagger是工具，Swagger工具使用OpenAPI标准来生成API文档。所以，现在说Swagger，其实更多时候指的是OpenAPI。 springdoc-openapi-ui就是基于OpenAPI 3.0的实现。
