10分钟上手JeecgBoot接口文档：从Swagger配置到RESTful API调用-优快云博客

10分钟上手JeecgBoot接口文档：从Swagger配置到RESTful API调用

【免费下载链接】jeecg-boot jeecgboot/jeecg-boot 是一个基于 Spring Boot 的 Java 框架，用于快速开发企业级应用。适合在 Java 应用开发中使用，提高开发效率和代码质量。特点是提供了丰富的组件库、模块化架构和自动化配置方式。项目地址: https://gitcode.com/GitHub_Trending/je/jeecg-boot

你还在为接口文档维护烦恼？团队协作中接口变更不同步？前端对接后端时参数混乱？本文将带你零基础掌握JeecgBoot框架下的接口文档自动生成方案，通过Swagger-UI+RESTful API设计，让接口管理效率提升10倍！读完本文你将学会：配置Swagger文档、理解API设计规范、前端调用示例及常见问题解决。

Swagger-UI自动文档：零代码实现接口可视化

JeecgBoot已内置Swagger3（OpenAPI）支持，通过简单配置即可生成交互式接口文档。核心配置位于jeecg-boot/jeecg-boot-base-core/src/main/java/org/jeecg/config/Swagger3Config.java，关键实现如下：

@Configuration
public class Swagger3Config implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 配置Swagger静态资源访问
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");
    }

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("JeecgBoot 后台服务API接口文档")
                        .version("3.8.3")
                        .description("后台API接口"))
                .components(new Components()
                        .addSecuritySchemes("X-ACCESS-TOKEN", 
                                new SecurityScheme()
                                        .type(SecurityScheme.Type.APIKEY)
                                        .in(SecurityScheme.In.HEADER)
                                        .name("X-ACCESS-TOKEN")));
    }
}

启动项目后，访问http://localhost:8080/doc.html即可打开文档界面，无需手动编写任何文档内容。系统会自动扫描所有@RestController注解的控制器，生成包含请求参数、响应格式、示例数据的完整文档。

RESTful API设计规范：JeecgBoot最佳实践

JeecgBoot严格遵循RESTful API设计原则，所有接口通过标准HTTP方法实现资源操作。以用户管理模块为例，SysUserController定义了完整的CRUD接口：

接口路径	请求方法	功能描述	权限要求
/sys/user/list	GET	获取用户列表	system:user:list
/sys/user/add	POST	创建用户	system:user:add
/sys/user/edit	PUT	更新用户	system:user:edit
/sys/user/delete	DELETE	删除用户	system:user:delete
/sys/user/queryById	GET	获取用户详情	system:user:queryById

核心注解使用示例

在控制器方法中添加Swagger注解可增强文档可读性：

@RestController
@RequestMapping("/sys/user")
public class SysUserController {
    @Operation(summary = "获取用户信息", description = "根据用户ID查询详细信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "String")
    @GetMapping("/queryById")
    public Result<SysUser> queryById(@RequestParam String id) {
        // 业务逻辑实现
    }
}

前端API调用：从文档到代码的无缝衔接

JeecgBoot前端框架（Vue3）已封装统一的API调用工具，位于jeecgboot-vue3/src/api/sys/user.ts，典型调用示例：

// 用户登录API
export function loginApi(params: LoginParams) {
  return defHttp.post<LoginResultModel>({
    url: '/sys/login',
    params,
  });
}

// 获取用户信息
export function getUserInfo() {
  return defHttp.get<GetUserInfoModel>({ 
    url: '/sys/user/getUserInfo' 
  });
}

调用流程：

从Swagger文档复制接口路径/sys/user/getUserInfo
使用defHttp工具发送请求
通过TypeScript接口定义参数和返回值类型

常见问题解决方案

1. 文档访问404

检查Swagger配置类是否添加@Configuration注解，确保Swagger3Config.java被Spring扫描到。

2. 权限拦截问题

Swagger文档默认排除登录相关接口的认证要求，配置位于：

Set<String> excludedPaths = new HashSet<>(Arrays.asList(
  "/sys/login", "/sys/phoneLogin", "/sys/captcha"
));

如需添加免认证接口，直接在集合中添加路径即可。

3. 接口未显示

确保控制器类添加@RestController注解，方法添加@RequestMapping或HTTP方法注解（@GetMapping/@PostMapping等）。

总结与展望

通过本文学习，你已掌握JeecgBoot接口文档的生成与使用全流程。Swagger-UI不仅解决了接口文档维护难题，更通过规范的RESTful API设计提升了团队协作效率。建议进一步探索：

自定义接口文档样式（修改Swagger配置）
添加接口测试用例（结合Postman）
集成接口版本管理（通过URL路径区分版本）

收藏本文，下次遇到接口对接问题时即可快速查阅！关注我们，下期将带来《JeecgBoot接口权限控制实战》。

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