在開發(fā)項(xiàng)目中，由于歷史或各種原因(日志/攔截等)在controller層使用了自定義注解，此時(shí)想用swagger2生成api文檔時(shí)會(huì)碰到一個(gè)很頭疼的重復(fù)說(shuō)明問(wèn)題

20180522150717595.png

那怎么能將@ApiOperation中的value替換為@Explain注解中的value呢~

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

查看源碼發(fā)現(xiàn)，文檔生成控制在springfox.documentation.spring.web.plugins.DocumentationPluginsManager中

operation相關(guān)

@Autowired
  @Qualifier("operationBuilderPluginRegistry")
  private PluginRegistry<OperationBuilderPlugin, DocumentationType> operationBuilderPlugins;

發(fā)現(xiàn)注入了OperationBuilderPlugin這個(gè)接口的實(shí)現(xiàn)類

執(zhí)行的方法

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

將執(zhí)行讀取到的的Bean容器中所有OperationBuilderPlugin實(shí)現(xiàn)類的apply方法

官方實(shí)現(xiàn)的OperationBuilderPlugin類上都標(biāo)有@Order(Ordered.HIGHEST_PRECEDENCE)

所以我們只需要實(shí)現(xiàn)OperationBuilderPlugin并將Order設(shè)置為官方之后即可

/*********源碼分析結(jié)束，以下為解決實(shí)現(xiàn)*************/

此示例僅實(shí)現(xiàn)以Explain注解中的value值替換@ApiOperation中的value值。若沒(méi)有@ApiOperation注解時(shí)，將Explain的值存入builder，更多實(shí)現(xiàn)邏輯可自己實(shí)現(xiàn)。

配置類：

@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注解的方法

替換實(shí)現(xiàn)：

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<ApiOperation> list = context.findAllAnnotations(ApiOperation.class);
        if (list.size() == 0) {
            List<Explain> explainList = context.findAllAnnotations(Explain.class);
            if (explainList.size() > 0) {
                Explain explain = explainList.get(0);
                context.operationBuilder().summary(explain.value());//替換默認(rèn)值
            }
        }
    }
 
    @Override
    public boolean supports(DocumentationType delimiter) {
        return true;
    }
 
}

如想修改@ApiParam等官方注解的替換及邏輯更改的同理

轉(zhuǎn)自: 會(huì)走路的300快