JeecgBoot文档生成：Swagger+Javadoc API文档

原创 于 2025-08-31 04:03:21 发布 · 990 阅读 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。

JeecgBoot文档生成：Swagger+Javadoc API文档

【免费下载链接】JeecgBoot 🔥企业级低代码平台集成了AI应用平台，帮助企业快速实现低代码开发和构建AI应用!前后端分离架构 SpringBoot，SpringCloud、Mybatis，Ant Design4、 Vue3.0、TS+vite！强大的代码生成器让前后端代码一键生成，无需写任何代码! 引领AI低代码开发模式: AI生成->OnlineCoding-> 代码生成-> 手工MERGE，显著的提高效率，又不失灵活~ 【免费下载链接】JeecgBoot 项目地址: https://gitcode.com/jeecgboot/JeecgBoot

概述

在企业级应用开发中，API文档的生成和维护是至关重要的环节。JeecgBoot作为一款优秀的企业级低代码平台，提供了完整的API文档生成解决方案，集成了Swagger和Javadoc两大主流文档工具。本文将深入解析JeecgBoot中API文档生成的实现原理、配置方法和最佳实践。

技术架构

JeecgBoot采用Knife4j作为Swagger的增强实现，结合Spring Boot的自动配置机制，提供了开箱即用的API文档功能。

核心依赖配置

<!-- knife4j OpenAPI3 支持 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
    <version>4.4.0</version>
</dependency>

<!-- 微服务网关 knife4j 支持 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
    <version>4.4.0</version>
</dependency>

Swagger配置详解

基础配置类

JeecgBoot通过Swagger2Config类实现Swagger的完整配置：

@Configuration
@EnableSwagger2WebMvc
@Import(BeanValidatorPluginsConfiguration.class)
public class Swagger2Config implements WebMvcConfigurer {

    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("org.jeecg"))
                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build()
                .securitySchemes(Collections.singletonList(securityScheme()))
                .securityContexts(securityContexts())
                .globalOperationParameters(setHeaderToken());
    }
}

API信息配置

private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
            .title("JeecgBoot 后台服务API接口文档")
            .version("1.0")
            .description("后台API接口")
            .contact(new Contact("北京国炬信息技术有限公司","www.jeccg.com","jeecgos@163.com"))
            .license("The Apache License, Version 2.0")
            .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
            .build();
}

安全认证配置

JeecgBoot支持JWT Token认证的API文档访问：

private List<Parameter> setHeaderToken() {
    ParameterBuilder tokenPar = new ParameterBuilder();
    List<Parameter> pars = new ArrayList<>();
    tokenPar.name(CommonConstant.X_ACCESS_TOKEN)
            .description("token")
            .modelRef(new ModelRef("string"))
            .parameterType("header")
            .required(false)
            .build();
    pars.add(tokenPar.build());
    return pars;
}

注解使用规范

控制器层注解

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

    @Autowired
    private ISysUserService sysUserService;

    @GetMapping("/list")
    @ApiOperation(value = "用户列表查询", notes = "分页查询用户信息")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "pageNo", value = "页码", required = true),
        @ApiImplicitParam(name = "pageSize", value = "每页条数", required = true)
    })
    public Result<IPage<SysUser>> queryPageList(SysUser user,
                                                @RequestParam(name = "pageNo", defaultValue = "1") Integer pageNo,
                                                @RequestParam(name = "pageSize", defaultValue = "10") Integer pageSize) {
        // 业务逻辑
    }
}

实体类注解

@Data
@TableName("sys_user")
@ApiModel(value = "系统用户对象", description = "系统用户表")
public class SysUser implements Serializable {

    @TableId(type = IdType.ASSIGN_ID)
    @ApiModelProperty(value = "主键ID")
    private String id;

    @ApiModelProperty(value = "用户名", required = true)
    private String username;

    @ApiModelProperty(value = "真实姓名")
    private String realname;

    @ApiModelProperty(value = "密码")
    private String password;

    @ApiModelProperty(value = "手机号")
    private String phone;

    @ApiModelProperty(value = "邮箱")
    private String email;
}

文档访问与使用

访问地址

环境类型访问地址说明
单体应用http://localhost:8080/jeecg-boot/doc.htmlKnife4j增强UI
微服务http://localhost:9999/doc.html网关聚合文档
Swagger原生http://localhost:8080/jeecg-boot/swagger-ui.html原生Swagger UI

功能特性对比

mermaid

Javadoc文档生成

Maven配置

JeecgBoot通过Maven插件实现Javadoc的自动生成：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>3.3.1</version>
    <configuration>
        <encoding>UTF-8</encoding>
        <docencoding>UTF-8</docencoding>
        <charset>UTF-8</charset>
        <skip>false</skip>
    </configuration>
    <executions>
        <execution>
            <id>attach-javadocs</id>
            <goals>
                <goal>jar</goal>
            </goals>
        </execution>
    </executions>
</plugin>

生成命令

# 生成Javadoc文档
mvn javadoc:javadoc

# 生成并打包Javadoc
mvn javadoc:jar

# 部署到站点
mvn site:deploy

高级配置与优化

多环境配置

# application-dev.yml
knife4j:
  enable: true
  production: false
  basic:
    enable: true
    username: admin
    password: 123456

# application-prod.yml  
knife4j:
  enable: false
  production: true

自定义文档分组

@Bean
public Docket customApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("自定义API")
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.custom.package"))
            .paths(PathSelectors.any())
            .build();
}

常见问题解决方案

1. 跨版本兼容性问题

// 解决Spring Boot 2.6+与Springfox兼容性问题
@Bean
public static BeanPostProcessor springfoxHandlerProviderBeanPostProcessor() {
    return new BeanPostProcessor() {
        @Override
        public Object postProcessAfterInitialization(Object bean, String beanName) {
            if (bean instanceof WebMvcRequestHandlerProvider) {
                customizeSpringfoxHandlerMappings(getHandlerMappings(bean));
            }
            return bean;
        }
    };
}

2. 资源路径配置

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("swagger-ui.html")
            .addResourceLocations("classpath:/META-INF/resources/");
    registry.addResourceHandler("doc.html")
            .addResourceLocations("classpath:/META-INF/resources/");
    registry.addResourceHandler("/webjars/**")
            .addResourceLocations("classpath:/META-INF/resources/webjars/");
}

最佳实践指南

代码规范

  1. 接口注释规范

    • 每个Controller类添加@Api注解说明模块功能
    • 每个方法添加@ApiOperation注解说明接口用途
    • 参数使用@ApiImplicitParam或@ApiParam注解

  2. 实体类注释规范

    • 类级别使用@ApiModel注解
    • 字段级别使用@ApiModelProperty注解
    • 必填字段明确标注required = true

文档维护

mermaid

性能优化建议

1. 生产环境配置

# 生产环境关闭Swagger
spring:
  profiles:
    active: prod

knife4j:
  enable: false
  production: true

2. 文档缓存策略

@Configuration
public class CacheConfig {
    
    @Bean
    public CacheManager cacheManager() {
        SimpleCacheManager cacheManager = new SimpleCacheManager();
        cacheManager.setCaches(Arrays.asList(
            new ConcurrentMapCache("apiDocs")
        ));
        return cacheManager;
    }
}

总结

JeecgBoot通过集成Knife4j和Swagger，提供了完整的API文档生成解决方案。其特点包括：

  1. 开箱即用：默认配置即可生成美观的API文档
  2. 安全认证：支持JWT Token等认证方式
  3. 多环境支持：开发测试生产环境灵活配置
  4. 增强功能：Knife4j提供离线文档、接口调试等增强功能
  5. 微服务支持：网关聚合多个服务的API文档

通过遵循本文的配置规范和最佳实践，开发者可以轻松生成和维护高质量的API文档，提升团队协作效率和系统可维护性。

温馨提示：本文档基于JeecgBoot 3.8.2版本编写，不同版本可能存在配置差异，请以实际版本为准。

【免费下载链接】JeecgBoot 🔥企业级低代码平台集成了AI应用平台，帮助企业快速实现低代码开发和构建AI应用!前后端分离架构 SpringBoot，SpringCloud、Mybatis，Ant Design4、 Vue3.0、TS+vite！强大的代码生成器让前后端代码一键生成，无需写任何代码! 引领AI低代码开发模式: AI生成->OnlineCoding-> 代码生成-> 手工MERGE，显著的提高效率，又不失灵活~ 【免费下载链接】JeecgBoot 项目地址: https://gitcode.com/jeecgboot/JeecgBoot

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值