IntelliJ IDEA快速生成RESTful接口文档详细指南

🚀 IntelliJ IDEA快速生成RESTful接口文档详细指南（2026版）

摘要

本文详细介绍了在IntelliJ IDEA中快速生成RESTful接口文档的三种主流方案：IDEA内置功能、第三方插件和代码注解方案。重点讲解了IDEA内置的HTTP Client工具和OpenAPI规范支持的使用方法，包括创建HTTP请求文件、环境变量配置、OpenAPI规范文件编写等实用技巧。文章还提供了方案对比表和使用建议，帮助开发者根据项目需求选择最适合的文档生成方式。通过清晰的代码示例和操作步骤，展示了如何高效利用IDEA工具链实现接口文档的快速生成与管理。

📋 目录

方案概览与选择
IDEA内置功能方案
插件方案详解
代码注解方案（Springdoc/Swagger）
最佳实践与对比
常见问题解决

一、方案概览与选择

1.1 三种主流方案对比

方案类型	适用场景	优点	缺点
IDEA内置功能	个人开发、快速测试	无需额外安装、集成度高	功能相对简单
第三方插件	团队协作、完整文档管理	功能强大、支持同步到平台	需要额外安装配置
代码注解	企业级项目、自动化文档	文档与代码强绑定、自动生成	需要添加依赖和注解

1.2 方案选择建议

bash 复制代码

# 个人快速开发
✅ 使用 IDEA 内置 HTTP Client + OpenAPI 支持

# 团队协作项目
✅ 使用 Apifox/Apidog 插件 + 云端同步

# 企业级Spring Boot项目
✅ 使用 Springdoc + Swagger UI + IDEA插件辅助

# 需要离线文档交付
✅ 使用 EasyApi 导出到 YApi/Apifox

二、IDEA内置功能方案

2.1 HTTP Client - 内置接口测试工具

创建HTTP请求文件

bash 复制代码

# 方法1：通过菜单创建
右键项目 → New → HTTP Request
命名为: api-test.http

# 方法2：快捷键创建
Ctrl + Alt + Shift + Insert (Windows/Linux)
Cmd + Option + N (macOS)

# 方法3：直接创建文件
在项目中创建 .http 或 .rest 后缀的文件
例如：user-api.http

HTTP请求文件示例

http 复制代码

### GET 请求示例
GET http://localhost:8080/api/users/1
Accept: application/json
Authorization: Bearer {{auth_token}}

### POST 请求示例
POST http://localhost:8080/api/users
Content-Type: application/json

{
  "username": "testuser",
  "email": "test@example.com",
  "password": "password123"
}

### PUT 请求示例
PUT http://localhost:8080/api/users/1
Content-Type: application/json

{
  "username": "updateduser",
  "email": "updated@example.com"
}

### DELETE 请求示例
DELETE http://localhost:8080/api/users/1
Authorization: Bearer {{auth_token}}

### 带查询参数
GET http://localhost:8080/api/users?status=active&page=1&size=10

### 文件上传
POST http://localhost:8080/api/upload
Content-Type: multipart/form-data; boundary=WebAppBoundary

--WebAppBoundary
Content-Disposition: form-data; name="file"; filename="test.jpg"
Content-Type: image/jpeg

< ./test.jpg
--WebAppBoundary--

快捷键与功能

bash 复制代码

# 快速生成请求模板
gtr  - 生成GET请求
ptr  - 生成POST请求
utr  - 生成PUT请求
dtr  - 生成DELETE请求

# 执行请求
Alt + Enter (Windows/Linux)
Option + Enter (macOS)
或点击请求左侧的绿色运行按钮

# 查看响应
响应会显示在下方的Response窗口
支持JSON、HTML、XML等格式高亮

环境变量配置

http 复制代码

# 创建 http-client.env.json 文件
{
  "dev": {
    "host": "localhost:8080",
    "auth_token": "dev_token_123",
    "api_version": "v1"
  },
  "prod": {
    "host": "api.example.com",
    "auth_token": "prod_token_456",
    "api_version": "v2"
  }
}

# 在HTTP文件中使用
GET http://{{host}}/api/{{api_version}}/users
Authorization: Bearer {{auth_token}}

2.2 OpenAPI 规范支持（内置插件）

启用OpenAPI插件

bash 复制代码

1. 打开 Settings (Ctrl+Alt+S)
2. 导航到：Plugins
3. 搜索 "OpenAPI Specification"
4. 确认已启用（默认已捆绑）
5. 重启IDEA

创建OpenAPI规范文件

yaml 复制代码

# api-spec.yaml
openapi: 3.0.0
info:
  title: User Management API
  description: API for managing user accounts
  version: 1.0.0
  contact:
    email: api@example.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html

servers:
  - url: http://localhost:8080/api/v1
    description: Development server
  - url: https://api.example.com/v1
    description: Production server

tags:
  - name: users
    description: User management operations
  - name: auth
    description: Authentication operations

paths:
  /users:
    get:
      tags: [users]
      summary: Get all users
      description: Returns a list of all users
      parameters:
        - name: page
          in: query
          description: Page number
          required: false
          schema:
            type: integer
            default: 1
        - name: size
          in: query
          description: Page size
          required: false
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    
    post:
      tags: [users]
      summary: Create a new user
      description: Creates a new user account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserInput'
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Invalid input

  /users/{id}:
    get:
      tags: [users]
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        username:
          type: string
          minLength: 3
          maxLength: 50
        email:
          type: string
          format: email
        createdAt:
          type: string
          format: date-time
      required:
        - id
        - username
        - email
    
    UserInput:
      type: object
      properties:
        username:
          type: string
        email:
          type: string
        password:
          type: string
          format: password
      required:
        - username
        - email
        - password

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

预览OpenAPI文档

bash 复制代码

# 在IDEA中预览
1. 打开 api-spec.yaml 文件
2. 点击右上角的 "Preview" 按钮
3. 选择 "Swagger UI" 或 "Redoc UI"
4. 交互式文档会在新窗口打开

# 快捷键
Ctrl + Shift + P (Windows/Linux)
Cmd + Shift + P (macOS)

三、插件方案详解

3.1 EasyApi - 轻量级接口文档生成

安装与配置

bash 复制代码

# 安装插件
1. 打开 Settings (Ctrl+Alt+S)
2. Plugins → Marketplace
3. 搜索 "EasyApi"
4. 点击 Install
5. 重启IDEA

# 配置插件
1. Settings → Other Settings → EasyApi
2. 配置YApi服务器地址（如果需要）
3. 配置项目Token
4. 设置导出格式（JSON、Markdown等）

使用方法

java 复制代码

// 示例Controller
@RestController
@RequestMapping("/api/users")
@Api(tags = "用户管理")
public class UserController {
    
    @GetMapping("/{id}")
    @ApiOperation("根据ID获取用户信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
    public ResponseEntity<User> getUserById(@PathVariable Long id) {
        // ...
    }
    
    @PostMapping
    @ApiOperation("创建新用户")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "username", value = "用户名", required = true),
        @ApiImplicitParam(name = "email", value = "邮箱", required = true),
        @ApiImplicitParam(name = "password", value = "密码", required = true)
    })
    public ResponseEntity<User> createUser(@RequestBody User user) {
        // ...
    }
}

// 快捷键生成文档
右键Controller类 → Generate → EasyApi
或
Alt + Insert → EasyApi

导出功能

bash 复制代码

# 导出到不同平台
1. 右键Controller或方法
2. 选择 "EasyApi" → "Export"
3. 选择导出目标：
   - YApi
   - Apifox
   - Postman
   - Markdown
   - JSON

# 批量导出
选中多个Controller → 右键 → EasyApi → Export All

3.2 Apifox Helper - 云端同步方案

安装与配置

bash 复制代码

# 安装插件
1. Settings → Plugins → Marketplace
2. 搜索 "Apifox Helper"
3. Install → Restart

# 配置Apifox
1. 访问 https://apifox.com 注册/登录
2. 进入项目设置 → 对外能力 → OpenAPI
3. 创建API访问令牌
4. 复制令牌

# 配置IDEA插件
1. Settings → Tools → Apifox Helper
2. 填写：
   - 项目ID
   - API令牌
   - 云端域名（默认）
3. 点击 Test Connection
4. Apply → OK

使用方法

java 复制代码

// 无需修改代码，插件自动扫描
@RestController
@RequestMapping("/api/orders")
public class OrderController {
    
    @GetMapping
    public List<Order> listOrders() {
        // ...
    }
    
    @PostMapping
    public Order createOrder(@RequestBody OrderRequest request) {
        // ...
    }
}

// 同步到Apifox
1. 右键Controller类
2. 选择 "Sync to Apifox"
3. 或使用快捷键：Ctrl + Alt + A

// 查看接口文档
1. 点击IDEA右侧的 "Apifox" 工具窗口
2. 展开接口树
3. 双击接口查看详细文档
4. 可直接在IDEA内测试接口

高级功能

bash 复制代码

# 环境管理
1. 在Apifox中创建多个环境（dev、test、prod）
2. 在IDEA中切换环境
3. 请求自动使用对应环境配置

# Mock数据
1. 在Apifox中设置Mock规则
2. 在IDEA中调用接口时自动返回Mock数据
3. 支持动态参数、随机数据

# 自动化测试
1. 在Apifox中创建测试用例
2. 在IDEA中运行测试
3. 查看测试报告

3.3 RestfulToolkit - 接口导航与测试

安装与配置

bash 复制代码

# 安装插件
1. Settings → Plugins → Marketplace
2. 搜索 "RestfulToolkit" 或 "RestfulToolkit-fix"
3. Install → Restart

# 配置（可选）
1. Settings → Other Settings → RestfulToolkit
2. 配置扫描路径
3. 配置端口（默认8080）

核心功能

bash 复制代码

# 1. 接口导航树
1. 打开 Tools → RestfulToolkit
2. 展开 "Services" 树
3. 查看所有RESTful接口
4. 双击接口跳转到代码定义

# 2. 快速跳转
Ctrl + \  (Windows/Linux)
Cmd + \  (macOS)
输入URL → 跳转到对应方法

# 3. 接口测试
1. 在Services树中右键接口
2. 选择 "Send Request"
3. 填写参数 → Send
4. 查看响应结果

# 4. 生成URL
1. 在Controller方法上右键
2. 选择 "Copy URL"
3. 自动拼接完整URL

# 5. 复制参数
1. 在方法上右键
2. 选择 "Copy Params"
3. 复制JSON格式参数

快捷键大全

快捷键	功能
`Ctrl + \`	URL跳转
`Ctrl + Alt + N`	快速导航
`Alt + Enter`	生成请求
`Ctrl + Shift + R`	刷新接口树

3.4 Apidog Helper - 类似Apifox

bash 复制代码

# 安装
Settings → Plugins → 搜索 "Apidog Helper"

# 配置
1. 访问 https://apidog.com
2. 获取项目ID和令牌
3. Settings → Tools → Apidog Helper
4. 填写配置 → Test Connection

# 使用
右键Controller → Sync to Apidog

四、代码注解方案（Springdoc/Swagger）

4.1 Spring Boot 3.x + Springdoc OpenAPI

添加依赖

xml 复制代码

<!-- Maven pom.xml -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.7.0</version>
</dependency>

<!-- 支持Spring Security -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
    <version>2.7.0</version>
</dependency>

gradle 复制代码

// Gradle build.gradle
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.7.0'
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-api:2.7.0'

配置文件

yaml 复制代码

# application.yml
springdoc:
  api-docs:
    path: /v3/api-docs
    enabled: true
  swagger-ui:
    path: /swagger-ui.html
    enabled: true
    tags-sorter: alpha
    operations-sorter: alpha
  default-flat-param-object: true
  show-actuator: true

# 自定义信息
springdoc:
  info:
    title: User Management API
    description: API for managing user accounts
    version: 1.0.0
    license:
      name: Apache 2.0
      url: http://www.apache.org/licenses/LICENSE-2.0.html
    contact:
      name: API Support
      url: http://www.example.com/support
      email: support@example.com

Java配置类

java 复制代码

@Configuration
@OpenAPIDefinition(
    info = @Info(
        title = "User Management API",
        version = "1.0.0",
        description = "API for managing user accounts",
        license = @License(name = "Apache 2.0", url = "http://www.apache.org/licenses/LICENSE-2.0.html"),
        contact = @Contact(name = "API Support", email = "support@example.com")
    ),
    servers = {
        @Server(url = "http://localhost:8080", description = "Development"),
        @Server(url = "https://api.example.com", description = "Production")
    }
)
public class OpenApiConfig {
    
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
            .components(new Components()
                .addSecuritySchemes("bearerAuth", 
                    new SecurityScheme()
                        .type(SecurityScheme.Type.HTTP)
                        .scheme("bearer")
                        .bearerFormat("JWT")
                )
            )
            .addSecurityItem(new SecurityRequirement().addList("bearerAuth"));
    }
}

Controller注解示例

java 复制代码

@RestController
@RequestMapping("/api/users")
@Tag(name = "用户管理", description = "用户CRUD操作")
public class UserController {
    
    @Autowired
    private UserService userService;
    
    @Operation(
        summary = "获取所有用户",
        description = "分页查询用户列表"
    )
    @ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "成功",
            content = @Content(array = @ArraySchema(schema = @Schema(implementation = User.class)))),
        @ApiResponse(responseCode = "401", description = "未授权"),
        @ApiResponse(responseCode = "500", description = "服务器错误")
    })
    @GetMapping
    public ResponseEntity<Page<User>> listUsers(
            @Parameter(description = "页码", example = "1") 
            @RequestParam(defaultValue = "1") int page,
            
            @Parameter(description = "每页大小", example = "10") 
            @RequestParam(defaultValue = "10") int size,
            
            @Parameter(description = "用户状态") 
            @RequestParam(required = false) String status) {
        
        PageRequest pageable = PageRequest.of(page - 1, size);
        Page<User> users = userService.findAll(status, pageable);
        return ResponseEntity.ok(users);
    }
    
    @Operation(summary = "根据ID获取用户")
    @GetMapping("/{id}")
    public ResponseEntity<User> getUserById(
            @Parameter(description = "用户ID", required = true, example = "1")
            @PathVariable Long id) {
        
        User user = userService.findById(id)
            .orElseThrow(() -> new ResourceNotFoundException("User not found"));
        return ResponseEntity.ok(user);
    }
    
    @Operation(summary = "创建新用户")
    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public ResponseEntity<User> createUser(
            @Parameter(description = "用户信息", required = true)
            @Valid @RequestBody UserCreateRequest request) {
        
        User user = userService.create(request);
        return ResponseEntity.status(HttpStatus.CREATED).body(user);
    }
    
    @Operation(summary = "更新用户信息")
    @PutMapping("/{id}")
    public ResponseEntity<User> updateUser(
            @Parameter(description = "用户ID", required = true)
            @PathVariable Long id,
            
            @Parameter(description = "更新后的用户信息", required = true)
            @Valid @RequestBody UserUpdateRequest request) {
        
        User user = userService.update(id, request);
        return ResponseEntity.ok(user);
    }
    
    @Operation(summary = "删除用户")
    @DeleteMapping("/{id}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void deleteUser(
            @Parameter(description = "用户ID", required = true)
            @PathVariable Long id) {
        
        userService.delete(id);
    }
}

DTO类注解

java 复制代码

@Schema(description = "用户创建请求")
public class UserCreateRequest {
    
    @Schema(description = "用户名", example = "john_doe", required = true)
    @NotBlank(message = "用户名不能为空")
    @Size(min = 3, max = 50, message = "用户名长度必须在3-50之间")
    private String username;
    
    @Schema(description = "邮箱", example = "john@example.com", required = true)
    @Email(message = "邮箱格式不正确")
    private String email;
    
    @Schema(description = "密码", example = "password123", required = true)
    @NotBlank(message = "密码不能为空")
    @Size(min = 6, message = "密码长度至少6位")
    private String password;
    
    @Schema(description = "手机号", example = "13800138000")
    private String phone;
    
    @Schema(description = "用户角色", example = "USER", allowableValues = {"USER", "ADMIN"})
    private String role = "USER";
    
    // getters and setters...
}

@Schema(description = "用户响应")
public class User {
    
    @Schema(description = "用户ID", example = "1")
    private Long id;
    
    @Schema(description = "用户名", example = "john_doe")
    private String username;
    
    @Schema(description = "邮箱", example = "john@example.com")
    private String email;
    
    @Schema(description = "手机号", example = "13800138000")
    private String phone;
    
    @Schema(description = "创建时间", example = "2024-01-01T10:00:00Z")
    private LocalDateTime createdAt;
    
    @Schema(description = "更新时间", example = "2024-01-01T10:00:00Z")
    private LocalDateTime updatedAt;
    
    // getters and setters...
}

访问Swagger UI

bash 复制代码

# 启动应用后访问
http://localhost:8080/swagger-ui.html

# 查看OpenAPI JSON
http://localhost:8080/v3/api-docs

# 导出OpenAPI YAML
http://localhost:8080/v3/api-docs.yaml

4.2 Spring Boot 2.x + Springfox Swagger

xml 复制代码

<!-- Maven依赖 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

java 复制代码

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
            .paths(PathSelectors.any())
            .build()
            .securitySchemes(Arrays.asList(apiKey()));
    }
    
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("User Management API")
            .description("API for managing user accounts")
            .version("1.0.0")
            .contact(new Contact("API Support", "http://www.example.com", "support@example.com"))
            .license("Apache 2.0")
            .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
            .build();
    }
    
    private ApiKey apiKey() {
        return new ApiKey("JWT", "Authorization", "header");
    }
}

五、最佳实践与对比

5.1 综合方案推荐

bash 复制代码

# 推荐组合方案

# 方案1：个人开发（最简）
✅ IDEA内置HTTP Client + Springdoc
- 无需额外插件
- 代码注解自动生成文档
- 内置工具测试接口

# 方案2：团队协作（推荐）
✅ Springdoc + Apifox Helper
- 代码注解保证文档准确性
- Apifox云端同步方便协作
- 支持Mock、测试、环境管理

# 方案3：企业级（完整）
✅ Springdoc + EasyApi + YApi
- Springdoc生成基础文档
- EasyApi导出到YApi平台
- YApi进行团队管理和版本控制

5.2 插件功能对比表

插件名称	文档生成	接口测试	云端同步	导出功能	学习成本
EasyApi	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐⭐	低
Apifox Helper	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	低
RestfulToolkit	⭐⭐⭐	⭐⭐⭐⭐⭐	❌	⭐⭐	低
Apidog Helper	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	低
IDEA内置	⭐⭐⭐	⭐⭐⭐⭐	❌	⭐⭐	极低

5.3 代码注解最佳实践

java 复制代码

// 1. 统一响应格式
@Schema(description = "统一响应格式")
public class ApiResponse<T> {
    
    @Schema(description = "状态码", example = "200")
    private Integer code;
    
    @Schema(description = "消息", example = "success")
    private String message;
    
    @Schema(description = "数据")
    private T data;
    
    @Schema(description = "时间戳", example = "1640995200000")
    private Long timestamp;
    
    // 构造方法、静态工厂方法...
    public static <T> ApiResponse<T> success(T data) {
        ApiResponse<T> response = new ApiResponse<>();
        response.setCode(200);
        response.setMessage("success");
        response.setData(data);
        response.setTimestamp(System.currentTimeMillis());
        return response;
    }
}

// 2. 分页响应
@Schema(description = "分页响应")
public class PageResponse<T> {
    
    @Schema(description = "数据列表")
    private List<T> content;
    
    @Schema(description = "总记录数", example = "100")
    private Long total;
    
    @Schema(description = "页码", example = "1")
    private Integer page;
    
    @Schema(description = "每页大小", example = "10")
    private Integer size;
    
    @Schema(description = "总页数", example = "10")
    private Integer totalPages;
    
    // getters and setters...
}

// 3. 全局异常处理
@RestControllerAdvice
public class GlobalExceptionHandler {
    
    @ExceptionHandler(ResourceNotFoundException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)
    @ResponseBody
    public ApiResponse<Object> handleNotFound(ResourceNotFoundException e) {
        return ApiResponse.error(404, e.getMessage());
    }
    
    @ExceptionHandler(MethodArgumentNotValidException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    @ResponseBody
    public ApiResponse<Object> handleValidation(MethodArgumentNotValidException e) {
        Map<String, String> errors = new HashMap<>();
        e.getBindingResult().getFieldErrors().forEach(error -> 
            errors.put(error.getField(), error.getDefaultMessage())
        );
        return ApiResponse.error(400, "参数验证失败", errors);
    }
}

// 4. 安全配置
@Configuration
@EnableWebSecurity
public class SecurityConfig {
    
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .csrf().disable()
            .authorizeHttpRequests(authz -> authz
                .requestMatchers("/api/public/**").permitAll()
                .requestMatchers("/swagger-ui/**", "/v3/api-docs/**").permitAll()
                .anyRequest().authenticated()
            )
            .httpBasic();
        return http.build();
    }
}

5.4 自动化文档生成脚本

bash 复制代码

#!/bin/bash
# generate-api-docs.sh

echo "🚀 开始生成API文档..."

# 1. 启动应用
echo "📦 启动Spring Boot应用..."
mvn spring-boot:run &
APP_PID=$!
sleep 10

# 2. 下载OpenAPI JSON
echo "📥 下载OpenAPI规范..."
curl -o openapi.json http://localhost:8080/v3/api-docs

# 3. 转换为Markdown
echo "📝 转换为Markdown格式..."
npx @mintlify/scrapinghub openapi2markdown openapi.json -o docs/api

# 4. 生成HTML文档
echo "🌐 生成HTML文档..."
npx redoc-cli bundle openapi.json -o docs/api.html

# 5. 停止应用
echo "⏹️ 停止应用..."
kill $APP_PID

echo "✅ API文档生成完成！"
echo "📄 文档位置：docs/api/"

yaml 复制代码

# GitHub Actions自动化
name: Generate API Docs

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  generate-docs:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v3
    
    - name: Set up JDK
      uses: actions/setup-java@v3
      with:
        java-version: '17'
        distribution: 'temurin'
    
    - name: Build with Maven
      run: mvn clean package -DskipTests
    
    - name: Start Application
      run: java -jar target/*.jar &
      env:
        SPRING_PROFILES_ACTIVE: test
    
    - name: Wait for application
      run: sleep 30
    
    - name: Generate OpenAPI docs
      run: |
        curl -o openapi.json http://localhost:8080/v3/api-docs
        npx redoc-cli bundle openapi.json -o api-docs/index.html
    
    - name: Upload docs
      uses: actions/upload-artifact@v3
      with:
        name: api-docs
        path: api-docs/

六、常见问题解决

6.1 插件安装问题

bash 复制代码

# 问题1：插件市场无法访问
解决方案：
1. 检查网络连接
2. 配置HTTP代理：
   Settings → Appearance & Behavior → System Settings → HTTP Proxy
3. 使用离线安装：
   - 下载插件ZIP包
   - Settings → Plugins → ⚙️ → Install Plugin from Disk

# 问题2：插件安装后不生效
解决方案：
1. 重启IDEA
2. 检查插件是否启用：Settings → Plugins → Installed
3. 清除缓存：File → Invalidate Caches → Invalidate and Restart

6.2 Springdoc配置问题

bash 复制代码

# 问题1：Swagger UI无法访问
可能原因：
1. 路径配置错误
2. Spring Security拦截
3. 依赖版本冲突

解决方案：
# 检查配置
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    enabled: true

# 配置Security放行
@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests()
            .antMatchers("/swagger-ui/**", "/v3/api-docs/**").permitAll()
            // ... 其他配置
    }
}

# 问题2：接口文档不显示
可能原因：
1. Controller包路径未扫描
2. 注解使用错误
3. 依赖版本不兼容

解决方案：
# 检查Docket配置
@Bean
public Docket api() {
    return new Docket(DocumentationType.OAS_30)
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 确保包路径正确
        .paths(PathSelectors.any())
        .build();
}

6.3 EasyApi同步问题

bash 复制代码

# 问题1：无法同步到YApi
可能原因：
1. YApi服务器地址配置错误
2. Token无效或过期
3. 网络连接问题

解决方案：
1. 检查Settings → Other Settings → EasyApi配置
2. 重新获取YApi Token
3. 测试网络连接：ping yapi服务器地址

# 问题2：接口参数不显示
可能原因：
1. 缺少@RequestBody或@RequestParam注解
2. DTO类缺少@Schema注解
3. 插件配置未勾选相应选项

解决方案：
# 添加注解
@PostMapping
public User createUser(
    @Parameter(description = "用户信息") // 添加Parameter注解
    @Valid @RequestBody UserCreateRequest request) {
    // ...
}

# 配置插件
Settings → Other Settings → EasyApi
- 勾选"Enable @Schema support"
- 勾选"Parse validation annotations"

6.4 IDEA内置HTTP Client问题

bash 复制代码

# 问题1：环境变量不生效
解决方案：
1. 确保http-client.env.json文件在项目根目录
2. 检查环境名称是否匹配
3. 重启IDEA

# 问题2：响应格式不正确
解决方案：
1. 检查Content-Type头
2. 确保请求体格式正确
3. 使用Response Handler：
   GET http://api.example.com/users
   Accept: application/json
   
   > {% 
     client.test("Status code is 200", function() {
       client.assert(response.status === 200, "Response status is not 200");
     });
   %}

七、总结与推荐

7.1 快速开始指南

bash 复制代码

# 5分钟快速生成文档

# 步骤1：添加依赖（Maven）
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.7.0</version>
</dependency>

# 步骤2：添加注解
@RestController
@Tag(name = "用户管理")
public class UserController {
    @GetMapping("/users")
    @Operation(summary = "获取用户列表")
    public List<User> getUsers() {
        // ...
    }
}

# 步骤3：启动应用
mvn spring-boot:run

# 步骤4：访问文档
http://localhost:8080/swagger-ui.html

# 完成！🎉

7.2 不同场景推荐

场景	推荐方案	理由
个人学习	IDEA内置 + Springdoc	简单、无需额外配置
小型项目	Springdoc + EasyApi	自动生成、支持导出
团队协作	Springdoc + Apifox	云端同步、协作方便
企业级	Springdoc + YApi + EasyApi	完整流程、版本管理
快速测试	RestfulToolkit	无需修改代码、快速测试

7.3 学习资源

bash 复制代码

# 官方文档
- OpenAPI: https://www.openapis.org/
- Springdoc: https://springdoc.org/
- Swagger: https://swagger.io/

# IDEA文档
- HTTP Client: https://www.jetbrains.com/help/idea/http-client-in-product-code-editor.html
- OpenAPI: https://www.jetbrains.com/help/idea/openapi.html

# 插件资源
- EasyApi: https://plugins.jetbrains.com/plugin/11975-easyapi
- Apifox Helper: https://plugins.jetbrains.com/plugin/16699-apifox-helper
- RestfulToolkit: https://plugins.jetbrains.com/plugin/10214-restfultoolkit

🎯 最终建议

对于大多数开发者，推荐使用以下组合：

bash 复制代码

✅ Springdoc OpenAPI (代码注解自动生成)
✅ Apifox Helper (云端同步协作)
✅ IDEA内置HTTP Client (快速测试)

优势：
- 文档与代码强绑定，自动更新
- 支持团队协作和版本管理
- 无需离开IDE即可完成开发、测试、文档生成
- 学习成本低，上手快

通过以上详细指南，你现在可以快速在IntelliJ IDEA中生成专业的RESTful接口文档了！🚀