JeecgBoot中Swagger接口文档配置与优化指南-代码聚汇网

JeecgBoot中Swagger接口文档配置与优化指南

SwaggerJeecgBootAPI文档

|难度：普通|阅读约 18 分钟

1. JeecgBoot中Swagger接口文档的配置与优化实战

作为一款基于SpringBoot的低代码开发平台，JeecgBoot在快速开发企业级应用方面表现出色。而在实际项目协作中，清晰规范的API文档是前后端高效联调的关键保障。本文将详细介绍如何在JeecgBoot项目中配置Swagger接口文档，并针对常见问题提供解决方案。

提示：本文基于JeecgBoot 3.4.4版本和SpringBoot 2.7.x环境验证，其他版本可能存在配置差异。

1.1 基础环境准备

首先确保项目中已包含Swagger相关依赖。JeecgBoot默认已集成Knife4j（Swagger的增强版），但需要检查pom.xml中是否包含以下关键依赖：

xml复制<!-- Knife4j核心依赖 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

<!-- SpringDoc OpenAPI (Swagger3) -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.11</version>
</dependency>

如果使用较新的JeecgBoot版本（如基于SpringBoot 3.x），需要对应调整依赖版本。SpringBoot 3.x环境下建议使用：

xml复制<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.1.0</version>
</dependency>

1.2 基础配置类编写

在config包下创建Swagger配置类，以下是完整示例：

java复制@Configuration
@EnableSwagger2
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("org.jeecg"))
                .paths(PathSelectors.any())
                .build()
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("JeecgBoot API文档")
                .description("JeecgBoot接口文档")
                .version("1.0")
                .build();
    }
    
    // 其他配置方法...
}

1.3 访问路径与安全配置

默认情况下，配置完成后可以通过以下地址访问文档：

Swagger原生UI：http://localhost:8080/swagger-ui.html
Knife4j增强UI：http://localhost:8080/doc.html

在生产环境中，建议通过以下方式增强安全性：

添加访问权限控制
配置只在开发环境启用
修改默认访问路径

可以在application.yml中添加配置：

yaml复制knife4j:
  enable: true
  production: false  # 生产环境关闭
  basic:
    enable: true
    username: admin
    password: 123456

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 常见问题解决方案

2.1 文档请求异常处理

问题1：Whitelabel Error Page

典型错误信息：

code复制Whitelabel Error Page
No static resource v3/api-docs/swagger-config.

解决方案：

检查是否添加了@EnableSwagger2注解
确认依赖版本兼容性
添加以下配置：

java复制@Bean
public WebMvcConfigurer webMvcConfigurer() {
    return new WebMvcConfigurer() {
        @Override
        public void addResourceHandlers(ResourceHandlerRegistry registry) {
            registry.addResourceHandler("doc.html")
                   .addResourceLocations("classpath:/META-INF/resources/");
            registry.addResourceHandler("/webjars/**")
                   .addResourceLocations("classpath:/META-INF/resources/webjars/");
        }
    };
}

问题2：Unexpected Token '<'错误

当访问接口文档时出现类似错误：

code复制SyntaxError: Unexpected token '<', "<!doctype "... is not valid JSON

这通常是由于：

未正确配置API路径
项目启用了权限拦截但未放行Swagger相关路径

解决方法：

在Security配置中添加放行规则：

java复制@Override
public void configure(WebSecurity web) throws Exception {
    web.ignoring().antMatchers(
        "/doc.html",
        "/webjars/**",
        "/swagger-resources/**",
        "/v2/api-docs",
        "/v3/api-docs",
        "/favicon.ico"
    );
}

检查application.yml中server.context-path配置是否正确

2.2 SpringBoot 3.x适配问题

对于使用SpringBoot 3.x的JeecgBoot项目，需要特别注意：

使用springdoc-openapi替代springfox
配置类需要调整：

java复制@Configuration
public class OpenApiConfig {
    
    @Bean
    public OpenAPI jeecgOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("JeecgBoot API")
                                .version("v1.0")
                                .description("JeecgBoot接口文档"))
                .externalDocs(new ExternalDocumentation()
                                .description("JeecgBoot文档")
                                .url("https://jeecg.com"));
    }
}

访问路径变为：
- OpenAPI: http://localhost:8080/swagger-ui/index.html
- Knife4j: http://localhost:8080/doc.html

3. 高级配置技巧

3.1 接口分组管理

大型项目中，合理的接口分组能显著提升文档可读性：

java复制// 系统模块API
@Bean
public Docket systemApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("系统管理")
            .apiInfo(systemApiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("org.jeecg.modules.system"))
            .paths(PathSelectors.any())
            .build();
}

// 业务模块API
@Bean
public Docket businessApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("业务模块")
            .apiInfo(businessApiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("org.jeecg.modules.business"))
            .paths(PathSelectors.any())
            .build();
}

3.2 接口注释规范

良好的注释是生成优质文档的基础：

java复制@Api(tags = "用户管理")
@RestController
@RequestMapping("/sys/user")
public class SysUserController {

    @ApiOperation("用户登录")
    @PostMapping("/login")
    public Result<JSONObject> login(
            @ApiParam(value = "用户名", required = true) @RequestParam String username,
            @ApiParam(value = "密码", required = true) @RequestParam String password) {
        // 方法实现
    }
    
    @ApiOperation(value = "获取用户列表", notes = "分页查询用户信息")
    @GetMapping("/list")
    public Result<IPage<SysUser>> queryPageList(
            @ApiParam("查询条件") SysUser user,
            @ApiParam("当前页") @RequestParam(defaultValue = "1") Integer pageNo,
            @ApiParam("每页大小") @RequestParam(defaultValue = "10") Integer pageSize) {
        // 方法实现
    }
}

3.3 全局参数配置

统一添加全局参数（如token认证）：

java复制private List<SecurityScheme> securitySchemes() {
    return Collections.singletonList(
        new ApiKey("Authorization", "Authorization", "header")
    );
}

private List<SecurityContext> securityContexts() {
    return Collections.singletonList(
        SecurityContext.builder()
            .securityReferences(defaultAuth())
            .forPaths(PathSelectors.regex("^(?!auth).*$"))
            .build()
    );
}

List<SecurityReference> defaultAuth() {
    AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
    return Collections.singletonList(
        new SecurityReference("Authorization", new AuthorizationScope[]{authorizationScope})
    );
}

4. 生产环境最佳实践

4.1 安全防护措施

禁用Swagger的HTTP TRACE方法：

java复制@Bean
public FilterRegistrationBean<HiddenHttpMethodFilter> hiddenHttpMethodFilter() {
    FilterRegistrationBean<HiddenHttpMethodFilter> filterRegistrationBean = 
        new FilterRegistrationBean<>(new HiddenHttpMethodFilter());
    filterRegistrationBean.setEnabled(false);
    return filterRegistrationBean;
}

添加IP白名单限制：

java复制@Bean
public FilterRegistrationBean<SwaggerAccessFilter> swaggerAccessFilter() {
    FilterRegistrationBean<SwaggerAccessFilter> registration = new FilterRegistrationBean<>();
    registration.setFilter(new SwaggerAccessFilter());
    registration.addUrlPatterns("/doc.html", "/swagger-ui.html", "/v2/api-docs");
    return registration;
}

4.2 性能优化建议

启用文档缓存：

yaml复制springdoc:
  cache:
    disabled: false

限制扫描的包路径，避免加载不必要的接口：

java复制.apis(RequestHandlerSelectors.basePackage("org.jeecg.modules"))

对于大型项目，考虑按模块拆分多个文档服务

4.3 文档导出与归档

Knife4j支持文档导出为多种格式：

Markdown格式
HTML格式
OpenAPI规范文件

可以通过以下方式实现定期归档：

java复制@Scheduled(cron = "0 0 2 * * ?")  // 每天凌晨2点执行
public void exportApiDocs() throws IOException {
    OpenAPI openAPI = openApiResource.getOpenApi();
    String json = Json.pretty(openAPI);
    
    // 保存为文件
    Files.write(Paths.get("/data/api-docs/"+LocalDate.now()+".json"), 
               json.getBytes(StandardCharsets.UTF_8));
    
    // 可选：转换为HTML/Markdown
    Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
            .withMarkupLanguage(MarkupLanguage.MARKDOWN)
            .build();
    Swagger2MarkupConverter.from(openAPI)
            .withConfig(config)
            .build()
            .toFile(Paths.get("/data/api-docs/latest"));
}

5. 与其他工具的集成

5.1 与YAPI对接

通过swagger.json自动同步到YAPI平台：

获取项目的swagger.json地址：
http://localhost:8080/v2/api-docs
使用YAPI的导入功能或通过命令行工具同步：

bash复制yapi import --config yapi.config.json

配置文件示例：

json复制{
  "type": "swagger",
  "[token](https://taotoken.net?utm_source=general)": "YAPI项目token",
  "file": "http://localhost:8080/v2/api-docs",
  "merge": "good",
  "server": "https://yapi.yourcompany.com"
}

5.2 与Postman集成

直接通过Swagger UI的"Export"功能导出为Postman Collection
或使用Postman的API导入功能，输入swagger.json地址
设置环境变量实现自动化测试

5.3 与Jenkins集成

实现文档的自动化更新与发布：

groovy复制pipeline {
    agent any
    
    stages {
        stage('Export API Docs') {
            steps {
                sh 'curl -o swagger.json http://localhost:8080/v2/api-docs'
                sh 'swagger2markup convert -i swagger.json -f output'
            }
        }
        
        stage('Deploy Docs') {
            steps {
                sshPublisher(
                    publishers: [
                        sshPublisherDesc(
                            configName: 'doc-server',
                            transfers: [
                                sshTransfer(
                                    sourceFiles: 'output/**',
                                    removePrefix: 'output',
                                    remoteDirectory: '/var/www/api-docs'
                                )
                            ]
                        )
                    ]
                )
            }
        }
    }
}

在实际项目中，合理的Swagger配置可以显著提升团队协作效率。建议根据项目规模选择合适的配置方案，并定期维护接口文档的准确性和完整性。对于特别敏感的项目，可以考虑使用Redoc等替代方案，或开发自定义的文档管理系统。