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 设置鉴权或仅内网访问。

0 赞

0 踩