Debian上使用Swagger的实用教程汇总
一 环境准备与安装
- 更新系统并安装基础工具：sudo apt update && sudo apt upgrade -y；安装 Node.js 与 npm（或 Docker 用于容器化部署）。Node 版本建议选择 LTS，以减少兼容性问题。
- 方式一 Node.js 生态：全局安装文档与 UI 工具，例如：sudo npm install -g swagger-jsdoc swagger-ui-express。
- 方式二 Docker 方式：安装 Docker 后拉取并运行官方镜像，例如：docker pull swaggerapi/swagger-ui；运行示例：docker run -d -p 8080:8080 swaggerapi/swagger-ui。
- 方式三 Java 生态（如 Spring Boot）：安装 openjdk-11-jdk，便于后续使用 Swagger/OpenAPI 相关依赖与工具。
二 在Node.js Express中集成Swagger UI
- 初始化项目并安装依赖：npm init -y；npm install express swagger-ui-express swagger-jsdoc。
- 创建规范文件（支持 swagger.json 或 swagger.yaml），定义 info、paths、components/schemas 等。
- 在应用中挂载 UI：使用 swagger-ui-express 提供 /api-docs 路由展示文档。
- 启动服务并访问：node app.js，打开浏览器访问 http://localhost:3000/api-docs。
三 在Java Spring Boot中集成Swagger
- 添加依赖（示例为 Springfox，适配 Spring Boot 2.x）：Maven 中加入 springfox-boot-starter 依赖（如版本 3.0.0）。
- 配置 Swagger（Java 配置类）：使用 @EnableSwagger2，创建 Docket Bean 指定扫描包与路径选择器。
- 访问文档：启动应用后打开 http://:/swagger-ui.html 查看与调试接口。
四 使用Docker部署Swagger UI
- 快速启动官方容器：docker run -d -p 8080:8080 swaggerapi/swagger-ui。
- 挂载本地规范文件：docker run -d -p 8080:8080 -v $(pwd)/swagger.json:/app/swagger.json swaggerapi/swagger-ui（将本地 swagger.json 挂载到容器内）。
- 指定版本运行：docker pull swaggerapi/swagger-ui:v4.15.5 后运行，便于版本可控。
五 规范编写与进阶实践
- 规范版本选择：传统 Swagger 2.0 与 OpenAPI 3.0+ 并存，注意与所用 Swagger UI 版本匹配。
- 生成与维护：在 Node.js 项目中可用 swagger-jsdoc 从注释/代码生成文档；也可维护静态 yaml/json 并配合 CI/CD 流程。
- 安全建议：生产环境应限制 /api-docs 的访问（如通过 Nginx 认证、内网访问或按需禁用）。
- 客户端/服务端代码生成：结合 openapi-generator 自动生成客户端 SDK 或服务器端桩代码，提升联调效率。
