如何通过Swagger注解为Java API添加请求/响应示例JSON？

Hey there! Let's sort out why your Swagger examples aren't showing up. I've dealt with similar hiccups when starting out, so here's a breakdown of what's going wrong and how to fix it:

1. First, fix the syntax error in your code #

Looking at your initial code snippet, you have an unclosed parenthesis in the @ApiParam annotation—this might be causing Swagger to ignore the example entirely. Here's the corrected version (note the closing ) after the example value):

@OtherAnnotationsHere
public ResponseObj doSomething(
    @ApiParam(name = "testname", value = "test value", required = true, example = "{\"userId\":\"1234\"}") 
    @RequestBody RequestObj req) {
    // some code here
}

2. Use the right approach for request/response examples (Swagger 2.x) #

The @ApiParam example attribute works best for simple query/path parameters, not for complex request bodies. For @RequestBody objects, you should define examples directly in your DTO classes using @ApiModel and @ApiModelProperty:

For your RequestObj class:

@ApiModel(description = "Request payload for the doSomething API")
public class RequestObj {
    @ApiModelProperty(
        value = "Unique ID of the user",
        required = true,
        example = "1234" // This will show up in the Swagger docs
    )
    private String userId;

    // Add other fields with their own @ApiModelProperty annotations
}

For your ResponseObj class:

@ApiModel(description = "Response payload for the doSomething API")
public class ResponseObj {
    @ApiModelProperty(
        value = "Status message of the operation",
        example = "Action completed successfully"
    )
    private String status;

    // Add other response fields with examples
}

If you want to show a full JSON example of the entire request/response body instead of per-field examples, use the requestExample or responseExample attributes in @ApiOperation:

@ApiOperation(
    value = "Performs an action with the given request",
    requestExample = "{\"userId\":\"1234\"}",
    responseExample = "{\"status\":\"Action completed successfully\"}"
)
public ResponseObj doSomething(@RequestBody RequestObj req) {
    // some code here
}

3. If you're using OpenAPI 3.x (springdoc-openapi) #

If you've moved to OpenAPI 3 (the newer standard), the annotations are different. Use @Schema instead of @ApiModelProperty, and @Parameter or @RequestBody with @Schema for request examples:

In your DTO class:

@Schema(description = "Request payload for the doSomething API")
public class RequestObj {
    @Schema(
        description = "Unique ID of the user",
        required = true,
        example = "1234"
    )
    private String userId;
}

Or directly in the method:

@PostMapping("/do-something")
public ResponseEntity<ResponseObj> doSomething(
    @RequestBody @Schema(example = "{\"userId\":\"1234\"}") RequestObj req) {
    // some code here
}

For full response examples in OpenAPI 3, you can use @ApiResponse with @Content and @ExampleObject:

@ApiResponse(
    responseCode = "200",
    description = "Success response",
    content = @Content(
        mediaType = "application/json",
        examples = @ExampleObject(value = "{\"status\":\"Action completed successfully\"}")
    )
)
public ResponseEntity<ResponseObj> doSomething(@RequestBody RequestObj req) {
    // some code here
}

Final checks #

• Make sure your Swagger dependencies are correctly included in your project (no conflicting versions).
• After making these changes, rebuild your project and refresh the Swagger UI—your examples should now appear!

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