本文共 4098 字，大约阅读时间需要 13 分钟。

在项目中集成 Swagger2 以外的 Document Framework（如 Knife4j）, 需要按照以下步骤进行配置：

1. 添加依赖

在项目的 pom.xml 文件中加入 Knife4j 的 Spring Boot 启动器依赖。

       
    
     com.github.xiaoymin
        
    
     knife4j-spring-boot-starter
        
    
     2.0.7
    
   

2. 配置 Swagger 文档

创建一个 Swagger 配置类，扩展开宠?

import com.github.xiaoymin.knife4j.spring.extension.OpenApiExtensionResolver;import lombok.AllArgsConstructor;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.builders.PathSelectors;import springfox.documentation.builders.RequestHandlerSelectors;import springfox.documentation.spi.DocumentationType;import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;@Configuration(proxyBeanMethods = false)@EnableSwagger2WebMvc@AllArgsConstructorpublic class DocumentConfig {    private final OpenApiExtensionResolver openApiExtensionResolver;    @Bean    public Docket appDocket() {        return new Docket(DocumentationType.SWAGGER_2)                .pathMapping("/")        // Swagger 文档路径                .apiInfo(new ApiInfoBuilder()                        .title("API 接口") // 文档标题                        .build())      // 配置完成后构建 ApiInfo 包括 title, description 等信息                .groupName("API")        // 文档分组                .select()              // 定义怎样选择接口                    .apis(RequestHandlerSelectors.basePackage("com.wolf.api.controller"))    // 扫描特定路径下的接口                    .paths(PathSelectors.any()) // 所有路径都会被选中                .build()              // 构建 Swagger 文档                .extensions(openApiExtensionResolver.buildExtensions("other")); // 扩展功能配置，默认为 "other"    }}

3. 配置静态资源过滤

在 SpringMVCConfig 类中添加资源过滤配置，确保 Swagger 文档可以被正确访问。

import org.springframework.context.annotation.Configuration;import org.springframework.context.annotation.ImportResource;import org.springframework.web.servlet_ResourceHandlerή;@Configurationpublic class SpringMVCConfig extends WebMvcConfigurationSupport {    @Override    protected void addResourceHandlers(ResourceHandlerRegistry registry) {        registry                // 将所有静态资源映射到根路径                .addResourceHandler("/**")                // 指定资源所在的路径, 这里的 /index.html 可以根据需要调整                .addResourceLocations("/", new String[]{"classpath:/index.html"}, new String[]{"classpath:/public/index.html"});    }}

4. 新增 application.yml 中的配置

在 application.yml 中添加 Swagger 文档相关配置, 处理权限放行：

# 配置 Swagger 文档启用knife4j:    enable: true# 配置图文文档documents:    - group: other      locations:          classpath: markdown/*      name: 其他文档# 其他配置, 包括权限配置auth:    cache-prefix: ${spring.application.name}    ignore:        urls:            - /api-docs/**   # Swagger 文档路径            - /other/**            - /webjars/**            - /**

5. 接口注解配置

在需要展示 Swagger 文档的接口中使用相关注解。

@RestController@Api(tags = "用户管理接口")@RequestMapping("/user")public class UserController {    @PostMapping("/")    @ApiOperation("添加用户接口")    @ApiImplicitParams({            @ApiImplicitParam(name = "username", value = "用户名", defaultValue = "李四", required = true),            @ApiImplicitParam(name = "address", value = "用户地址", defaultValue = "深圳", required = true)    })    public RespBean addUser(            @RequestParam(name = "username", required = true) String username,            String address    ) {        return new RespBean();    }    @GetMapping("/")    @ApiOperation("查询用户接口")    @ApiImplicitParam(name = "id", value = "用户编号", defaultValue = "99", required = true)    public User getUserById(            @PathVariable(name = "id") Integer id    ) {        User user = new User();        user.setId(id);        return user;    }    @PutMapping("/{id}")    @ApiOperation("修改用户接口")    public User updateUserById(            @RequestBody User user    ) {        return user;    }}

6. 注意事项

• 依赖版本：确保添加的 knife4j-spring-boot-starter 的版本与项目需求匹配。
• 文档扩展：如果需要额外的 markdown 文档, 创建相应的 markdown 文件放在项目根目录。
• 权限配置：如果项目使用权限框架, 确保 Swagger 文档路径未被过滤.
• 资源映射：静态资源的映射路径需与 Swagger 文档路径兼容即可.

建立完上述配置后, 应该能够ativas 生成 markdown 格式的 Swagger 文档, 并在应用启动后可通过指定 URL 访问.