5分钟上手！Jeesite接口文档自动生成全攻略-优快云博客

5分钟上手！Jeesite接口文档自动生成全攻略

【免费下载链接】jeesite Java rapid development platform, based (Spring Boot, Spring MVC, Apache Shiro, MyBatis, Beetl, Bootstrap, AdminLTE), online code generation, including modules: Organization, role users, menu and button authorization, data permissions, system parameters, content management, workflow, etc. Loose coupling design is adopted; one key skin switch; account security Settings, password policies; Online scheduled task configuration; Support cluster, support SAAS; Support for multiple data sources 项目地址: https://gitcode.com/gh_mirrors/jee/jeesite

你是否还在为手动编写API文档浪费30%开发时间？是否因前后端接口对接不清晰导致联调效率低下？本文将带你5分钟实现Jeesite项目的Swagger集成，自动生成标准化接口文档，让团队协作效率提升50%。

一、项目结构速览

Jeesite作为Java快速开发平台，其核心接口定义位于以下目录：

用户接口：packages/core/api/sys/user.ts
菜单接口：packages/core/api/sys/menu.ts
系统配置：packages/core/api/sys/config.ts

二、集成准备工作

1. 环境要求

JDK 1.8+
Spring Boot 2.6.x
Maven 3.6+

2. 依赖引入

在pom.xml中添加Swagger相关依赖：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

三、核心配置实现

1. 创建Swagger配置类

在src/main/java/com/jeesite/modules/sys/config目录下创建SwaggerConfig.java：

@Configuration
@EnableOpenApi
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.jeesite.modules"))
                .paths(PathSelectors.any())
                .build();
    }
    
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Jeesite API文档")
                .description("基于Swagger自动生成的接口文档")
                .version("1.0.0")
                .build();
    }
}

2. 接口注解示例

以用户管理接口为例，在user.ts中添加Swagger注解：

/**
 * 用户管理接口
 * @remarks 提供用户CRUD、密码修改等功能
 */
export const userListData = (params?: User | any) =>
  defHttp.post<Page<User>>({ url: adminPath + '/sys/user/listData', params });

/**
 * 修改密码接口
 * @param {Object} params - 请求参数
 * @param {string} params.oldPassword - 原密码
 * @param {string} params.newPassword - 新密码
 */
export const infoSavePwd = (params?: any) => {
  params.oldPassword = encryptByBase64(params.oldPassword);
  params.newPassword = encryptByBase64(params.newPassword);
  return defHttp.post<User>({ url: adminPath + '/sys/user/infoSavePwd', params });
};

四、文档访问与使用

1. 启动项目

执行以下命令启动应用：

mvn spring-boot:run

2. 访问文档

在浏览器中输入地址：http://localhost:8080/swagger-ui/index.html

3. 核心功能

接口列表查看
请求参数自动校验
在线接口调试
接口文档导出

五、高级配置技巧

1. 接口分组

通过@Api(tags = "用户管理")实现接口分组管理，使文档结构更清晰。

2. 权限控制

在Swagger配置中添加安全上下文：

.securitySchemes(Arrays.asList(
    new ApiKey("token", "token", "header")
))
.securityContexts(Arrays.asList(
    SecurityContext.builder()
        .securityReferences(Arrays.asList(
            new SecurityReference("token", new AuthorizationScope[]{})))
        .build()
))

3. 自定义UI

替换默认Swagger UI为Knife4j增强版，提供更友好的中文界面：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

六、常见问题解决

1. 接口未显示

检查：

包扫描路径是否正确
接口方法是否添加@ApiOperation注解

2. 类型转换错误

确保实体类字段添加正确的Swagger注解：

export interface User extends BasicModel<User> {
  /** 用户编码 */
  userCode?: string;
  /** 登录账号 */
  loginCode?: string;
}

七、总结

通过本文的步骤，你已经掌握了在Jeesite项目中集成Swagger的完整流程。自动化接口文档不仅能大幅减少重复工作，还能提升团队协作效率。更多高级功能可参考：

立即行动，让你的API文档从此"自己写自己"！

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