SpringBoot集成Swagger-UI后POST请求参数未显示，如何配置？

Hey there, let's break down why your /create endpoint isn't showing the request body schema in Swagger UI and how to fix it. This is a common issue, usually tied to missing annotations or incorrect Swagger configuration.

核心原因排查 #

The main culprits here are typically:

• Your User entity class isn't being scanned by Swagger, or lacks annotations that tell Swagger to generate its schema.
• Your Swagger configuration isn't set up to include the package where your User class lives.
• You're using the wrong annotations for your Swagger version (Springfox vs. SpringDoc, which matters a lot for Spring Boot 2.x vs 3.x).

分版本解决方案（Springfox vs SpringDoc） #

First, confirm which Swagger library you're using—this changes everything.

情况1：使用Springfox（Spring Boot 2.x 常用，已停止维护） #

If you're using springfox-boot-starter in your pom.xml or build.gradle:

1. 给User实体类添加Swagger注解
   Add @ApiModel and @ApiModelProperty to describe the class and its fields. Swagger needs these to generate the schema:

   import io.swagger.annotations.ApiModel;
   import io.swagger.annotations.ApiModelProperty;
   
   @ApiModel(description = "用户实体信息")
   public class User {
       @ApiModelProperty(value = "用户ID", example = "1")
       private Long id;
   
       @ApiModelProperty(value = "用户名", required = true, example = "alice")
       private String username;
   
       @ApiModelProperty(value = "用户邮箱", required = true, example = "alice@example.com")
       private String email;
   
       // Getters and Setters
   }
   

2. 完善控制器的Swagger注解
   Add @ApiOperation and @ApiParam to clarify the endpoint and request body:

   import io.swagger.annotations.ApiOperation;
   import io.swagger.annotations.ApiParam;
   import org.springframework.http.ResponseEntity;
   import org.springframework.web.bind.annotation.PostMapping;
   import org.springframework.web.bind.annotation.RequestBody;
   import org.springframework.web.bind.annotation.RequestMapping;
   import org.springframework.web.bind.annotation.RestController;
   
   @RestController
   @RequestMapping("/users")
   public class UsersController {
   
       @ApiOperation(value = "创建新用户", notes = "通过JSON请求体提交用户信息完成创建")
       @PostMapping("/create")
       public ResponseEntity<User> createUser(
               @ApiParam(value = "完整的用户信息JSON", required = true) 
               @RequestBody User user) {
           // 你的业务逻辑代码
           return ResponseEntity.ok(user);
       }
   }
   

3. 检查Swagger配置类
   Make sure your Docket configuration scans the packages containing both your controller and entity class:

   import org.springframework.context.annotation.Bean;
   import org.springframework.context.annotation.Configuration;
   import springfox.documentation.builders.PathSelectors;
   import springfox.documentation.builders.RequestHandlerSelectors;
   import springfox.documentation.spi.DocumentationType;
   import springfox.documentation.spring.web.plugins.Docket;
   import springfox.documentation.swagger2.annotations.EnableSwagger2;
   
   @Configuration
   @EnableSwagger2
   public class SwaggerConfig {
       @Bean
       public Docket api() {
           return new Docket(DocumentationType.SWAGGER_2)
                   .select()
                   // 替换成你的控制器和实体类所在的包
                   .apis(RequestHandlerSelectors.basePackage("com.yourproject"))
                   .paths(PathSelectors.any())
                   .build();
       }
   }
   

情况2：使用SpringDoc（Spring Boot 3.x 推荐，官方支持） #

If you're using springdoc-openapi-starter-webmvc-ui (the modern replacement for Springfox):

1. 给User实体类添加@Schema注解
   SpringDoc uses OpenAPI 3 annotations instead of the old Swagger 2 ones:

   import io.swagger.v3.oas.annotations.media.Schema;
   
   @Schema(description = "用户实体信息")
   public class User {
       @Schema(description = "用户ID", example = "1")
       private Long id;
   
       @Schema(description = "用户名", required = true, example = "bob")
       private String username;
   
       @Schema(description = "用户邮箱", required = true, example = "bob@example.com")
       private String email;
   
       // Getters and Setters
   }
   

2. 更新控制器的注解
   Use @Operation and @Parameter for OpenAPI 3:

   import io.swagger.v3.oas.annotations.Operation;
   import io.swagger.v3.oas.annotations.Parameter;
   import io.swagger.v3.oas.annotations.media.Content;
   import io.swagger.v3.oas.annotations.media.Schema;
   import io.swagger.v3.oas.annotations.responses.ApiResponse;
   import org.springframework.http.ResponseEntity;
   import org.springframework.web.bind.annotation.PostMapping;
   import org.springframework.web.bind.annotation.RequestBody;
   import org.springframework.web.bind.annotation.RequestMapping;
   import org.springframework.web.bind.annotation.RestController;
   
   @RestController
   @RequestMapping("/users")
   public class UsersController {
   
       @Operation(summary = "创建新用户", description = "提交用户JSON信息完成账户创建")
       @ApiResponse(responseCode = "200", description = "创建成功",
                   content = @Content(schema = @Schema(implementation = User.class)))
       @PostMapping("/create")
       public ResponseEntity<User> createUser(
               @Parameter(description = "完整的用户信息JSON", required = true)
               @RequestBody User user) {
           // 你的业务逻辑代码
           return ResponseEntity.ok(user);
       }
   }
   

3. 配置SpringDoc扫描规则
   Create a configuration bean to specify which packages to scan:

   import org.springdoc.core.models.GroupedOpenApi;
   import org.springframework.context.annotation.Bean;
   import org.springframework.context.annotation.Configuration;
   
   @Configuration
   public class SpringDocConfig {
       @Bean
       public GroupedOpenApi publicApi() {
           return GroupedOpenApi.builder()
                   .group("user-management-api")
                   // 替换成你的控制器和实体类所在的包
                   .packagesToScan("com.yourproject.controller", "com.yourproject.entity")
                   .build();
       }
   }
   

最后验证步骤 #

1. Restart your Spring Boot application.
2. Navigate to Swagger UI (usually http://localhost:8080/swagger-ui.html for Springfox, or http://localhost:8080/swagger-ui/index.html for SpringDoc).
3. Check the /users/create endpoint—you should now see the request body schema with all fields, required markers, and examples.

内容的提问来源于stack exchange，提问作者Gnik