Java后端工程化：霸王餐项目中接口文档自动化生成与维护方案

在“霸王餐”平台（baodanbao.com.cn）的多团队协作开发中，接口文档若依赖人工维护，极易出现版本滞后、描述错误等问题。为此，我们采用Springdoc OpenAPI 3（Swagger 3）实现接口文档自动生成，并结合CI/CD流程确保文档与代码强一致。

集成Springdoc OpenAPI

在baodanbao-web模块引入依赖：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.6.0</version>
</dependency>

启动后访问/swagger-ui.html即可查看交互式文档。

全局OpenAPI配置

通过@OpenAPIDefinition定义项目元信息：

// baodanbao/com/cn/config/OpenApiConfig.java
package baodanbao.com.cn.config;

import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.OpenAPI;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI baodanbaoOpenAPI() {
        return new OpenAPI()
            .info(new Info()
                .title("霸王餐开放API")
                .description("面向外卖平台的霸王餐资格核验与权益发放接口")
                .version("v1.2.0"));
    }
}

Controller接口注解化

使用@Operation、@Parameter等注解描述接口语义：

// baodanbao/com/cn/controller/QualifyController.java
package baodanbao.com.cn.controller;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/v1")
public class QualifyController {

    @PostMapping("/qualify/check")
    @Operation(summary = "校验用户是否具备霸王餐资格",
               description = "根据用户ID与商户ID调用远程服务判断是否可享霸王餐",
               responses = {
                   @ApiResponse(responseCode = "200", description = "成功",
                       content = @Content(schema = @Schema(implementation = QualifyResponse.class)))
               })
    public QualifyResponse checkQualify(
        @Parameter(description = "用户唯一标识", required = true)
        @RequestBody QualifyRequest request) {
        // 调用Service逻辑
        return qualifyService.check(request.getUserId(), request.getMerchantId());
    }
}

请求与响应体也需标注：

// baodanbao/com/cn/model/QualifyRequest.java
package baodanbao.com.cn.model;

import io.swagger.v3.oas.annotations.media.Schema;

public class QualifyRequest {

    @Schema(description = "用户ID", example = "user_12345", requiredMode = Schema.RequiredMode.REQUIRED)
    private String userId;

    @Schema(description = "商户ID", example = "merchant_67890", requiredMode = Schema.RequiredMode.REQUIRED)
    private String merchantId;

    // getters/setters
}

// baodanbao/com/cn/model/QualifyResponse.java
package baodanbao.com.cn.model;

import io.swagger.v3.oas.annotations.media.Schema;

public class QualifyResponse {

    @Schema(description = "是否具备资格", example = "true")
    private boolean qualified;

    @Schema(description = "资格判定原因", example = "新用户专享")
    private String reason;

    // constructors, getters/setters
}

分组与安全认证配置

按模块分组并配置Token鉴权：

@Bean
public GroupedOpenApi qualifyApi() {
    return GroupedOpenApi.builder()
        .group("资格核验")
        .pathsToMatch("/api/v1/qualify/**")
        .build();
}

@Bean
public GroupedOpenApi rewardApi() {
    return GroupedOpenApi.builder()
        .group("权益发放")
        .pathsToMatch("/api/v1/reward/**")
        .build();
}

全局添加Header参数：

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
        .addSecurityItem(new SecurityRequirement().addList("ApiKey"))
        .components(new Components()
            .addSecuritySchemes("ApiKey",
                new SecurityScheme()
                    .name("X-Access-Token")
                    .type(SecurityScheme.Type.APIKEY)
                    .in(SecurityScheme.In.HEADER)));
}

CI/CD中自动生成JSON文档

在构建阶段输出OpenAPI JSON文件，供前端或第三方集成：

# build.sh
mvn clean package -DskipTests
curl http://localhost:8080/v3/api-docs > openapi-baodanbao.json

或通过Maven插件直接生成：

<plugin>
    <groupId>io.github.kbuntrock</groupId>
    <artifactId>openapi-maven-plugin</artifactId>
    <version>1.0.0</version>
    <executions>
        <execution>
            <goals><goal>openapi</goal></goals>
        </execution>
    </executions>
    <configuration>
        <outputFileName>baodanbao-api-spec</outputFileName>
        <outputDirectory>${project.build.directory}/docs</outputDirectory>
    </configuration>
</plugin>

生成的baodanbao-api-spec.json可提交至Git仓库或发布到内部文档站点。

禁止生产环境暴露UI

通过Profile控制Swagger UI仅在开发环境启用：

# application-prod.yml
springdoc:
  swagger-ui:
    enabled: false
  api-docs:
    enabled: false

或通过条件注解：

@Profile("!prod")
@Configuration
public class SwaggerConfig { /* ... */ }

通过上述方案，“霸王餐”项目的接口文档实现零人工维护、实时同步、安全可控，显著提升前后端协作效率与系统可靠性。

本文著作权归 俱美开放平台 ，转载请注明出处！