Swagger多标签API如何配置不同标签下的差异化描述？

方案1：拆分接口方法（简单直接） #

Swagger原生的@ApiOperation不支持为同一个接口的不同Tag配置独立描述，最直观的解决方式是创建两个映射到同一URL的接口方法，分别绑定对应的Tag和描述，业务逻辑抽成公共方法避免重复：

@ApiOperation(value = "readplans", nickname="readplans-tag1", notes = "readplansfortag1", tags = {"tag1"})
@RequestMapping(value = "/readplans", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_VALUE)
public ResponseEntity<String[]> readplansForTag1() {
    return readplansInternal();
}

@ApiOperation(value = "readplans", nickname="readplans-tag2", notes = "readplansfortag2", tags = {"tag2"})
@RequestMapping(value = "/readplans", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_VALUE)
public ResponseEntity<String[]> readplansForTag2() {
    return readplansInternal();
}

// 抽离业务逻辑到私有方法，保证功能一致
private ResponseEntity<String[]> readplansInternal() {
    log.info("readAddonPlansByBasePlan() - start");
    String[] a = {"plana","planb","planc"};
    log.info("readAddonPlansByBasePlan() - end");
    return new ResponseEntity<>(a, HttpStatus.OK);
}

• 两个方法的nickname必须不同，避免Swagger文档生成冲突
• 前端调用仍使用同一个/readplans接口，完全不影响正常业务
• 顺便修正了你原代码里的语法错误：数组声明应为String[]，响应状态需用HttpStatus.OK而非字符串"OK"

方案2：自定义Swagger插件（无侵入修改） #

如果不想拆分接口方法，可以通过自定义Swagger扩展插件，在文档生成阶段根据Tag自动替换描述：

1. 实现Swagger的OperationBuilderPlugin接口：

@Component
public class TagSpecificNotesPlugin implements OperationBuilderPlugin {

    @Override
    public void apply(OperationContext context) {
        Operation operation = context.operationBuilder().build();
        // 按逗号分割原notes中的两个描述
        String[] notesArr = operation.getNotes().split(",\\s*");
        if (notesArr.length != 2) {
            return;
        }
        // 获取当前处理的Tag
        String currentTag = context.getTags().stream().findFirst().orElse("");
        // 根据Tag替换对应描述
        if ("tag1".equals(currentTag)) {
            context.operationBuilder().notes(notesArr[0]);
        } else if ("tag2".equals(currentTag)) {
            context.operationBuilder().notes(notesArr[1]);
        }
    }

    @Override
    public boolean supports(DocumentationType documentationType) {
        // 适配OpenAPI 3.0，若使用Swagger 2.0则替换为DocumentationType.SWAGGER_2
        return DocumentationType.OAS_30.equals(documentationType);
    }
}

2. 保持原接口代码不变（仅修正语法错误）：

@ApiOperation(value = "readplans", nickname="readplans",notes = "readplansfortag1, readplansfortag2", tags = {"tag1","tag2"})
@RequestMapping(value = "/readplans", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_VALUE)
public ResponseEntity<String[]> readplans() {
    log.info("readAddonPlansByBasePlan() - start");
    String[] a = {"plana","planb","planc"};
    log.info("readAddonPlansByBasePlan() - end");
    return new ResponseEntity<>(a, HttpStatus.OK);
}

• 该方案无需修改业务接口结构，适合对代码整洁度要求较高的场景
• 需根据项目实际使用的Swagger/OpenAPI版本调整supports方法中的枚举值

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