REST接口开发中怎么使用 Swagger 生成接口文档-java教程-PHP中文网

swagger生成接口文档的核心是“代码即文档”，通过注解（java/springdoc）或源码注释（go/swag）自动提取并渲染为可交互ui，无需手写yaml或单独维护文档文件。

rest接口开发中怎么使用 swagger 生成接口文档

Swagger 生成接口文档的核心是“代码即文档”——把接口描述写进代码或注释里，工具自动提取并渲染成可交互的网页。不需要手写 YAML，也不依赖单独维护文档文件。

Java（Spring Boot）项目接入 Swagger

主流做法是集成 Springfox Swagger2 或更现代的 Springdoc OpenAPI（推荐 Springdoc，原生支持 OpenAPI 3，无侵入、配置简洁）。

在 pom.xml 中添加 Springdoc 依赖（以 Maven 为例）：

<dependency><br><groupid>org.springdoc</groupid><br><artifactid>springdoc-openapi-ui</artifactid><br><version>1.7.0</version><br></dependency>

启动项目后，默认访问 http://localhost:8080/swagger-ui.html（旧版）或 http://localhost:8080/swagger-ui/index.html（Springdoc 默认路径），即可看到自动生成的 UI 页面

用 @Operation、@Parameter、@ApiResponse 等注解补充说明，增强文档可读性。例如：

@Operation(summary = "根据ID查询用户", description = "返回指定ID的用户完整信息")<br>
@Parameter(name = "id", description = "用户唯一标识", required = true)

Go（Gin）项目接入 Swagger

Go 没有运行时注解，所以靠源码注释 + 命令行工具生成文档数据。

Alibabacloud Sdk Client Initialization For Java

在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。

下载

在 main.go 顶部添加全局注释（必须）：

// @title 用户服务 API 文档<br>
// @version 1.0<br>
// @description 这是基于 Gin 的 RESTful 用户管理接口<br>
// @host localhost:8080<br>
// @BasePath /api/v1

在每个 handler 函数上方添加接口级注释，例如：

// @Summary 获取用户列表<br>
// @Tags 用户<br>
// @Param page query int false "页码" default(1)<br>
// @Success 200 {array} User "用户列表"<br>
// @Router /users [get]

执行 swag init（需提前安装 swag CLI），会在项目根目录生成 docs/ 文件夹

在路由中引入并注册：

import _ "your-project/docs"<br>
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

通用要点与避坑提醒

无论哪种语言，关键逻辑一致：声明 → 扫描 → 渲染。

只暴露需要的接口：通过包扫描路径（Java）或路由前缀（Go）控制范围，避免把健康检查、内部监控等接口也暴露到文档中
参数类型要写准：比如 query 参数用 query，path 参数用 path，body 用 body，否则 UI 上无法正确生成表单或示例请求
响应结构尽量用实体类/结构体标注：比写 {object} 更可靠，能自动推导字段名和类型，提升前端对接效率
生产环境建议关闭 Swagger UI：通过配置项（如 Springdoc 的 springdoc.api-docs.enabled=false）禁用，或用 profile 控制，防止敏感接口被随意探测

整个过程不复杂但容易忽略细节。只要注释写清楚、路径配对、工具链跑通，就能让接口文档和代码始终同步。