Swagger参数显示异常：新增参数不显示及Delete API头部参数缺失

Hey there, let's tackle these two Swagger parameter glitches one by one—they're pretty common, so I’ve got some practical fixes to walk you through:

1. New API Parameters Not Showing Up in Swagger #

Here are the first things to check:

• Verify Swagger/OpenAPI annotations are correctly applied:
  • If you’re using Spring Boot with Swagger 2.0, make sure your parameters are tagged with @ApiParam, and request bodies use @RequestBody alongside @ApiModel/@ApiModelProperty on your DTO fields.
  • For OpenAPI 3.0, use @Parameter for individual params and @Schema on DTOs instead. Missing these annotations is the #1 culprit here.
• Check your Swagger scan scope:
  • Double-check your Swagger configuration class (like SwaggerConfig or OpenApiConfig)—ensure the basePackage value includes the package where your new API resides. If the package isn’t scanned, Swagger won’t pick up the endpoint at all.
• Rule out accidental parameter exclusion:
  • Did you add @JsonIgnore to a field but still want it visible in Swagger? Add @Schema(accessMode = Schema.AccessMode.READ_WRITE) to override this. Also, check if your config has global parameter filters hiding certain types.
• Restart your application:
  • Hot deployment can be flaky sometimes. A full restart might force Swagger to refresh its API documentation.

2. Updated Delete API Parameters Visible Only in "Try It" (Not in Header Section) #

This one usually ties to Swagger UI’s default behavior or annotation misconfiguration:

• Check your parameter’s location annotation:
  • If you’re using @RequestBody for your Delete API, Swagger UI won’t display this in the top "Parameters" section—only in the "Request Body" tab of the "Try It" panel. This aligns with HTTP conventions (Delete requests typically don’t carry bodies), but if you need it to show up, you’ll need to adjust your OpenAPI config to allow request bodies for Delete methods.
• Ensure hidden attributes aren’t enabled:
  • Double-check if your parameter has @Parameter(hidden = true) or @ApiParam(hidden = true) set. Even if "Try It" shows it (due to cache), the header section will hide it if this flag is on.
• Clear browser cache:
  • Swagger UI often caches old API specs. Do a hard refresh (Ctrl+F5 on Windows, Cmd+Shift+R on Mac) or clear your browser’s cache to load the latest version.
• Confirm OpenAPI version compatibility:
  • If you migrated from Swagger 2.0 to OpenAPI 3.0, some annotation behaviors changed. For example, @ApiImplicitParam for Delete requests might need adjusted paramType values to display correctly in the header section.

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