swagger2使用自定义注解生成文档

在开发项目中，由于历史或各种原因(日志/拦截等)在controller层使用了自定义注解，此时想用swagger2生成api文档时会碰到一个很头疼的重复说明问题

20180522150717595.png

那怎么能将@ApiOperation中的value替换为@Explain注解中的value呢~

/**********部分源码分析 不想看的直接拉到最后********/

查看源码发现，文档生成控制在springfox.documentation.spring.web.plugins.DocumentationPluginsManager中

operation相关

@Autowired
  @Qualifier("operationBuilderPluginRegistry")
  private PluginRegistry operationBuilderPlugins;

发现注入了OperationBuilderPlugin这个接口的实现类

执行的方法

public Operation operation(OperationContext operationContext) {
    for (OperationBuilderPlugin each : operationBuilderPlugins.getPluginsFor(operationContext.getDocumentationType())) {
      each.apply(operationContext);
    }
    return operationContext.operationBuilder().build();
  }

将执行读取到的的Bean容器中所有OperationBuilderPlugin实现类的apply方法

官方实现的OperationBuilderPlugin类上都标有@Order(Ordered.HIGHEST_PRECEDENCE)

所以我们只需要实现OperationBuilderPlugin并将Order设置为官方之后即可

/*********源码分析结束，以下为解决实现*************/

此示例仅实现以Explain注解中的value值替换@ApiOperation中的value值。若没有@ApiOperation注解时，将Explain的值存入builder，更多实现逻辑可自己实现。

配置类：

@Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                /**apiInfo**/
                .apiInfo(apiInfo())
                /**useDefaultResponseMessages**/
                .useDefaultResponseMessages(false)
                /**alternateTypeRules**/
                .alternateTypeRules(AlternateTypeRules.newRule(QueryPage.class, QueryPageTemplate.class))
                .alternateTypeRules(AlternateTypeRules.newRule(ResultEntity.class, ResultEntityTemplate.class))
                /**select**/
                .select()
                /**apis**/
                .apis(RequestHandlerSelectors.withMethodAnnotation(Explain.class))
                /**paths**/
                .paths(PathSelectors.any()).build();
    }

仅扫描有Explain注解的方法

替换实现：

import java.util.List;
 
import org.springframework.core.Ordered;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;
 
import io.swagger.annotations.ApiOperation;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.OperationBuilderPlugin;
import springfox.documentation.spi.service.contexts.OperationContext;
import top.wboost.common.annotation.Explain;
 
@Component
@Order(Ordered.HIGHEST_PRECEDENCE - 10)
public class ExplainOperationBuilderPlugin2 implements OperationBuilderPlugin {
 
    @Override
    public void apply(OperationContext context) {
        List list = context.findAllAnnotations(ApiOperation.class);
        if (list.size() == 0) {
            List explainList = context.findAllAnnotations(Explain.class);
            if (explainList.size() > 0) {
                Explain explain = explainList.get(0);
                context.operationBuilder().summary(explain.value());//替换默认值
            }
        }
    }
 
    @Override
    public boolean supports(DocumentationType delimiter) {
        return true;
    }
 
}

如想修改@ApiParam等官方注解的替换及逻辑更改的同理

转自: 会走路的300快