springboot集成swagger实战指南

<think>好的，用户想要在Spring Boot项目中集成Swagger的实战教程或示例代码。我需要先回顾一下之前提供的引用内容，确保信息准确。根据引用[1]、[2]、[3]，用户可能已经了解了一些基本步骤，比如添加Maven依赖、配置Swagger以及生成API文档的方法。用户可能需要详细的步骤和代码示例。 首先，我应该分步骤说明如何集成Swagger3，因为引用[1]提到的是Swagger3，而引用[3]是关于Swagger2的。需要注意两者的依赖和配置可能不同。需要确认用户是否需要Swagger2还是Swagger3的教程，但问题中没有明确说明，所以可能需要分别说明或者选择较新的版本。 然后，示例代码部分需要正确，比如Maven依赖是否使用正确的groupId和artifactId。例如，Swagger3可能需要使用springdoc-openapi而不是springfox，因为springfox可能不再维护。不过引用[1]提到的是Swagger3，但引用中的依赖可能还是springfox的，这可能有误。需要核对正确的依赖配置，避免给用户错误的信息。 此外，配置类需要正确使用注解，比如在Spring Boot中启用Swagger的注解是@EnableOpenApi还是@EnableSwagger2，这取决于使用的库。例如，springdoc-openapi使用@EnableOpenApi，而springfox可能使用@EnableSwagger2。 另外，用户可能需要了解如何自定义API信息，比如标题、版本、描述等，以及如何分组API。在引用[1]中提到了这些内容，所以需要包含这些步骤。 还要注意生成的问题部分，需要生成与集成Swagger相关的问题，比如版本差异、配置参数或常见问题解决。 最后，确保回答结构清晰，步骤明确，代码正确，并且符合用户的要求。可能需要指出Swagger2和Swagger3的区别，帮助用户选择适合的版本，并引用正确的资料。</think>### Spring Boot集成Swagger3实战指南 #### 一、环境准备 1. 创建Spring Boot项目（2.6+版本） 2. 选择Web模块依赖 #### 二、添加依赖 ```xml <!-- SpringDoc OpenAPI (Swagger3) --> <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-ui</artifactId> <version>1.7.0</version> </dependency> ``` *注意：Spring Boot 3.x请使用springdoc-openapi-starter-webmvc-ui* #### 三、基础配置 ```java @Configuration @OpenAPIDefinition(info = @Info( title = "订单服务API文档", version = "1.0", description = "电商系统订单模块接口文档" )) public class SwaggerConfig { @Bean public OpenAPI customOpenAPI() { return new OpenAPI() .components(new Components()) .info(new Info() .title("API文档") .version("1.0") .contact(new Contact().name("技术支持").url("http://example.com")) ); } } ``` #### 四、接口文档注解示例 ```java @RestController @RequestMapping("/api/orders") @Tag(name = "订单管理", description = "订单相关操作接口") public class OrderController { @Operation(summary = "创建订单", description = "根据购物车信息生成新订单") @ApiResponses({ @ApiResponse(responseCode = "200", description = "订单创建成功"), @ApiResponse(responseCode = "400", description = "无效的请求参数") }) @PostMapping public ResponseEntity<Order> createOrder(@RequestBody OrderDTO dto) { // 业务逻辑 } @Operation(summary = "获取订单详情") @Parameter(name = "orderId", description = "订单ID", required = true) @GetMapping("/{orderId}") public Order getOrder(@PathVariable Long orderId) { // 业务逻辑 } } ``` #### 五、访问文档 启动应用后访问： - API文档：`http://localhost:8080/swagger-ui.html` - JSON格式：`http://localhost:8080/v3/api-docs` #### 六、高级配置（application.yml） ```yaml springdoc: swagger-ui: path: /api-docs.html tags-sorter: alpha operations-sorter: alpha api-docs: path: /api-docs packages-to-scan: com.example.controller default-consumes-media-type: application/json default-produces-media-type: application/json ``` [^1][^2]