用API文档生成插件，让接口协作不再抓瞎

写接口文档像点外卖一样简单

做网站开发时，前后端对接最怕啥？不是技术难题，而是沟通成本。后端改了个字段，前端不知道；前端急着联调，文档还没影儿。这时候，一个趁手的API文档生成插件，能省下大把扯皮时间。

以前我都是手动写Markdown，更新一次得翻好几页，错漏难免。后来用了API文档生成插件，代码里加个注释，文档自动就出来了，连颜色排版都帮你配好。

主流插件怎么选？

Swagger（现在叫OpenAPI）是最常见的选择。只要在代码里加上@ApiOperation、@ApiParam这类注解，启动服务后访问/swagger-ui.html，所有接口一目了然。Spring Boot项目集成特别顺，加个starter依赖就行。

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

另一个是YApi，适合团队协作。它支持从代码注释抓取，也能手动导入JSON。我们组用它做权限划分，测试人员只能看文档不能改，开发才能编辑，管理起来挺清爽。

真实场景：三天搞定对接

上个月帮朋友搭小程序后台，他找了个外包做前端。两边没碰过面，全靠文档对接。我在Spring Boot里配了Swagger，把文档链接发过去，对方第二天就把列表页和详情页做出来了。中间改了两个字段名，我一提交，他那边刷新页面就看到了更新，连微信都没多聊一句。

这种效率，换作以前手写文档根本不敢想。光是“你改了哪儿”“我没收到通知”就能来回好几轮。

别忽视的小细节

生成文档时注意别把敏感接口暴露出去。比如/actuator这类管理端点，要在配置里过滤掉。Swagger可以用@Hidden注解，或者在配置类里指定扫描路径。

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
        .components(new Components())
        .addSecurityItem(new SecurityRequirement()
            .addList("bearerAuth"))
        .info(new Info().title("用户中心API")
            .description("仅供内部服务调用"));
}

另外，文档里加上示例值会更友好。比如date字段写个"2024-05-20T10:30:00Z"，比只写“时间戳”清楚多了。前端同事说，看到示例能直接复制去测，少犯一半错误。

现在我新项目起步，第一件事就是把文档插件配好。不为别的，就为少接那句“你这接口到底返回啥？”