Debian环境下Swagger API文档维护指南
在Debian系统中，首先需要安装Swagger相关工具。对于Java Spring Boot项目，通过Maven添加springfox-swagger2和springfox-swagger-ui依赖（版本需适配Spring Boot版本，如2.9.2）；对于PHP项目，使用Composer安装zircote/swagger-php；对于C#项目，通过NuGet安装Swashbuckle。这些工具是生成和展示Swagger文档的核心依赖。
配置Swagger以扫描项目中的API并生成文档。以Spring Boot为例，创建SwaggerConfig配置类，使用@Configuration和@EnableSwagger2注解启用Swagger，通过Docket Bean配置文档信息（如标题、版本、联系人）及扫描路径（指定Controller所在包）。在Controller方法上使用Swagger注解（如@ApiOperation描述接口功能、@ApiParam描述参数、@ApiResponse描述响应），确保文档与代码逻辑一致。
通过自动化流程减少手动维护成本。对于Spring Boot项目，每次代码编译部署后，Swagger会自动扫描代码中的注解并生成最新文档（访问http://localhost:8080/swagger-ui.html查看）；对于PHP项目，运行vendor/bin/openapi --output ./docs --path ./src命令，将代码中的Swagger注解转换为openapi.yaml文件；对于C#项目，运行项目后，通过Swagger UI（默认路径/swagger）查看实时文档。
采用合适的版本控制方法，避免新旧API冲突。常见方式包括：
/api/v1/users、/api/v2/users），通过Spring Boot的Docket配置不同分组（groupName）和路径过滤（PathSelectors.ant("/api/v1/**")）；X-API-Version: 1）指定版本，适用于需要隐藏路径变化的场景；Accept或Content-Type头中指定媒体类型（如application/vnd.myapp.v1+json），适合RESTful API的版本管理。swagger-core 2.2.29+），在apiInfo中明确API版本，提升文档规范性。为Swagger UI添加安全保护，防止未授权访问。以Spring Boot为例，创建SwaggerAuthMiddleware中间件，拦截/swagger-ui路径的请求，要求客户端提供Basic认证（用户名/密码）。配置中间件后，只有通过认证的用户才能访问Swagger UI页面，确保API文档的隐私性。
将Swagger规范文件（如swagger.yaml、openapi.json）纳入版本控制系统（如Git），跟踪文档变更历史。当API发生变化时，更新注解或规范文件，重新生成文档并提交到版本库。团队成员可通过版本库查看历史版本，对比差异，确保文档与API实现同步。对于大型项目，可使用Swagger Editor在线编写和预览文档，通过GitHub等平台协作维护。
