spring cloud alibaba 集成 knife4j (一)

携手创作，共同成长！这是我参与「掘金日新计划 · 8 月更文挑战」的第2天，点击查看活动详情

使用swagger3

Swagger 是一套基于 OpenAPI 规范（OpenAPI Specification，OAS）构建的开源工具，后来成为了 Open API 标准的主要定义者，现在最新的版本为17年发布的 Swagger3（Open Api3）。

由于swagger2已经停止维护，先集成swagger3

当前版本配置

<spring-boot.version>2.6.3</spring-boot.version>

<spring-cloud.version>2021.0.1</spring-cloud.version>

<com-alibaba-cloud.version>2021.0.1.0</com-alibaba-cloud.version>

引入依赖

        commmon模块pom引入
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

配置SwaggerConfig

@Slf4j
@Configuration
@EnableOpenApi
public class Swagger3Config {
    /** 默认的排除路径，排除Spring Boot默认的错误处理路径和端点(在解析的url规则之上)  /* /error，由于服务通常加前缀，所以前面/*忽略前缀 */
    private static final List<String> DEFAULT_EXCLUDE_PATH = Arrays.asList("/error","/actuator/**","/*/error");

    /** swagger会解析的url规则 */
    private static final String BASE_PATH = "/**";


    @Bean(value = "createRestApi")
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(groupApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("young.abandon.controller"))
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo groupApiInfo() {
        return new ApiInfoBuilder()
                .title("swagger-3 ！！！")
                .description("<div style='font-size:14px;color:red;'>swagger- 3 -demo RESTful APIs</div>")
                .termsOfServiceUrl("http://www.group.com/")
                .contact(new Contact("hy", "qwer", "group@qq.com"))
                .version("1.0")
                .build();
    }
    
}

路径匹配

报错信息

Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException

因为Springfox 使用的路径匹配是基于AntPathMatcher的，而Spring Boot 2.6.X使用的是PathPatternMatcher。若要使用swagger3.0，修改yml配置，否则报空指针

Spring Boot版本	Swagger 版本
2.6.5	3.0.0

  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher
  main:
    allow-circular-references: true

认证模块actuator 报错

blog.csdn.net/qq_40977118…

actuator endpoints在2.6之后也使用基于 PathPattern 的 URL 匹配

*而且actuator endpoints的路径匹配策略无法通过配置属性进行配置，
*如果同时使用Actuator和Springfox，会导致程序启动失败，所以只是进行上面的设置是不行的。

在认证模块添加配置

@Slf4j
@Configuration
public class Swagger3Config {
    @Bean
    public WebMvcEndpointHandlerMapping webEndpointServletHandlerMapping(WebEndpointsSupplier webEndpointsSupplier,
                                                                         ServletEndpointsSupplier servletEndpointsSupplier, ControllerEndpointsSupplier controllerEndpointsSupplier,
                                                                         EndpointMediaTypes endpointMediaTypes, CorsEndpointProperties corsProperties,
                                                                         WebEndpointProperties webEndpointProperties, Environment environment) {
        List<ExposableEndpoint<?>> allEndpoints = new ArrayList<>();
        Collection<ExposableWebEndpoint> webEndpoints = webEndpointsSupplier.getEndpoints();
        allEndpoints.addAll(webEndpoints);
        allEndpoints.addAll(servletEndpointsSupplier.getEndpoints());
        allEndpoints.addAll(controllerEndpointsSupplier.getEndpoints());
        String basePath = webEndpointProperties.getBasePath();
        EndpointMapping endpointMapping = new EndpointMapping(basePath);
        boolean shouldRegisterLinksMapping =
                webEndpointProperties.getDiscovery().isEnabled() && (StringUtils.hasText(basePath)
                        || ManagementPortType.get(environment).equals(ManagementPortType.DIFFERENT));
        return new WebMvcEndpointHandlerMapping(endpointMapping, webEndpoints, endpointMediaTypes,
                corsProperties.toCorsConfiguration(), new EndpointLinksResolver(allEndpoints, basePath),
                shouldRegisterLinksMapping, null);
    }

}

接口api-docs返回信息未正确解析

CommonResponseAdvice对api-docs接口返回信息做了包装，所以取消这个接口的统一返回结果

controller方法中使用相应注解

@Api(value = "订单value", tags = "订单模块")
@RestController
@RequestMapping("/user")
public class OrderController {


    @ApiOperation(value = "查询订单列表")
    @PostMapping(value = "/list")
    public List<Map<Object, Object>> list() {
        List<Map<Object, Object>> list = Lists.newArrayList();

        return list;
    }

    @ApiOperation(value = "根据订单id查询订单详情")
    @GetMapping("/queryById")
    public Map<Object, Object> queryById(@RequestParam(value = "id") String id) {
        HashMap<Object, Object> map = Maps.newHashMap();

        return map;
    }

    /**
     * 测试用的接口
     */
    @RequestMapping("/test")
    public String test(String str) {
        return str;
    }

    /**
     * 用户登录接口
     */
    @ApiOperation(value = "用户登录接口")
    @PostMapping("/login")
    public UserVo login(String userName, String password) {
        return new UserVo(userName, password);
    }
}

启动项目，访问地址：http://localhost:8080/swagger-ui/index.html

至此已经可以正常访问swaggerui