Ubuntu Swagger的API文档如何生成

Ubuntu 上生成 Swagger API 文档的实用步骤

一 准备环境

• 安装 Node.js 与 npm（Ubuntu 20.04/22.04 常见仓库版本即可）：
  • 命令：sudo apt update && sudo apt install -y nodejs npm
• 可选：安装 Docker，便于快速运行 Swagger Editor/UI 容器，避免本地 Node 环境差异。
• 说明：Swagger 生态的规范为 OpenAPI（常见为 YAML/JSON），工具包括 Swagger Editor（编辑与校验）、Swagger UI（展示与调试）、以及代码注解生成/导出工具（如 OpenAPI Generator）。

二 方式一 手动编写 OpenAPI 规范并用 Swagger UI 预览

• 安装并启动 Swagger Editor（本地静态服务方式）：
  • 下载发布包并解压（示例版本号可按需替换）：
    • wget https://github.com/swagger-api/swagger-editor/archive/refs/tags/v3.16.1.tar.gz
    • tar -xvf v3.16.1.tar.gz && cd swagger-editor-3.16.1
  • 安装依赖并启动：
    • npm install && npm install -g http-server
    • http-server -p 8080
  • 浏览器访问：http://localhost:8080，在编辑器中编写或导入 swagger.yaml/swagger.json 并校验。
• 使用 Docker 运行 Editor（更省事）：
  • docker pull swaggerapi/swagger-editor
  • docker run -p 8080:8080 swaggerapi/swagger-editor
• 预览文档（Swagger UI 静态服务方式，与 Editor 分离）：
  • 下载并启动 UI：
    • wget https://github.com/swagger-api/swagger-ui/archive/refs/tags/v3.48.0.tar.gz
    • tar -xvf v3.48.0.tar.gz && cd swagger-ui-3.48.0
    • npm install && npm install -g http-server
    • http-server -p 8081
  • 在 UI 页面将 URL 指向你的 swagger.yaml/swagger.json（可使用本地文件路径或远程地址）。

三 方式二 集成到 Node.js Express 应用

• 安装依赖：
  • npm install express swagger-ui-express yamljs
• 最小可用示例（读取本地 swagger.yaml 并在 /api-docs 提供 UI）：
  • 代码示例：

    • const express = require('express');
      const swaggerUi = require('swagger-ui-express');
      const YAML = require('yamljs');
      const app = express();
      const swaggerDocument = YAML.load('./path/to/your/swagger.yaml');
      app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
      const PORT = process.env.PORT || 3000;
      app.listen(PORT, () => console.log(`Server running on ${PORT}`));
      

  • 启动服务后访问：http://localhost:3000/api-docs。
• 说明：也可将 swagger.json 直接 require 加载；路径前缀（如 /api-docs）可自定义。

四 方式三 从代码注解自动生成 OpenAPI 文档

• Go 项目（swaggo/swag）
  • 安装：go install github.com/swaggo/swag/cmd/swag@latest
  • 初始化：swag init（生成 docs 目录与代码）
  • 在代码中使用注释（如 // @Summary、// @Param 等），再次 swag init 更新文档。
• Spring Boot 项目（Springfox/Springdoc）
  • 添加依赖（示例为 Springfox Boot Starter）：
    • Maven：

      • <dependency>
          <groupId>io.springfox</groupId>
          <artifactId>springfox-boot-starter</artifactId>
          <version>3.0.0</version>
        </dependency>
        

  • 启动项目后访问：http://localhost:8080/swagger-ui/（Springfox 3.x 默认路径）。
• 其他语言/框架：使用 OpenAPI Generator 从规范生成客户端/服务端桩代码与文档，或结合各语言生态的注解工具链实现“代码即文档”。

五 常见问题与建议

• CORS：若 API 与文档不在同域，需在后端开启 CORS 允许来源，避免浏览器拦截。
• 规范版本：推荐使用 OpenAPI 3.0.x；字段名与结构需与所用 UI/工具版本匹配。
• 路径与静态资源：部署时将 swagger.yaml/json 放在可访问路径，或通过反向代理/容器卷挂载到 Swagger UI 可访问位置。
• 安全：生产环境不要暴露编辑端；对 /api-docs 或 /swagger-ui 设置鉴权或仅内网访问。