在 Swagger/OpenAPI 场景下，方法级注释 = @Operation + @Parameter（或 @Parameters）。
下面给出两种常用写法（任选其一即可），复制即可让 Swagger-UI 显示中文说明。

写法 1：注解直接落在方法参数上（最直观）

java

复制

@Operation(summary = "语音助手指令入口", 
           description = "支持语音文件或已转写文本，自动选择工具并返回答案")
@PostMapping(value = "/aivoicecmd",
             consumes = MediaType.MULTIPART_FORM_DATA_VALUE,
             produces = MediaType.APPLICATION_JSON_VALUE)
public R<AiCmdResult> aiVoiceCmd(
        @Parameter(description = "语音二进制文件", required = false, example = "binary")
        @RequestPart(value = "voiceFile", required = false) MultipartFile voiceFile,

        @Parameter(description = "已转写文本", required = false, example = "杭州天气怎么样？")
        @RequestParam(value = "voiceText", required = false) String voiceText,

        @Parameter(description = "期望指令类型", required = false, example = "consult")
        @RequestParam(value = "cmd", required = false) String cmd) {

    return R.ok(voiceService.doCommand(voiceFile, voiceText, cmd));
}

写法 2：参数较多时集中写 @Parameters

java

复制

@Operation(summary = "语音助手指令入口", 
           description = "支持语音文件或已转写文本，自动选择工具并返回答案")
@Parameters({
    @Parameter(name = "voiceFile", description = "语音二进制文件", required = false, example = "binary"),
    @Parameter(name = "voiceText", description = "已转写文本", required = false, example = "杭州天气怎么样？"),
    @Parameter(name = "cmd", description = "期望指令类型", required = false, example = "consult")
})
@PostMapping(value = "/aivoicecmd",
             consumes = MediaType.MULTIPART_FORM_DATA_VALUE,
             produces = MediaType.APPLICATION_JSON_VALUE)
public R<AiCmdResult> aiVoiceCmd(
        @RequestPart(value = "voiceFile", required = false) MultipartFile voiceFile,
        @RequestParam(value = "voiceText", required = false) String voiceText,
        @RequestParam(value = "cmd", required = false) String cmd) {

    return R.ok(voiceService.doCommand(voiceFile, voiceText, cmd));
}

效果
启动后访问 Swagger-UI，即可看到：

• 接口名称 = 语音助手指令入口

• 每个参数均有中文描述 + 示例值，不再需要翻源码。