linux swagger怎么生成文档

linux

小樊

2026-10-24 04:41:42

栏目: 智能运维

在 Linux 环境下生成 Swagger 文档，通常取决于你使用的后端语言/框架。下面按常见场景给你总结几种最实用的方式。

一、Spring Boot（Java，最常见）

1️⃣ 使用 Springdoc OpenAPI（推荐）

依赖（Maven）

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.3.0</version>
</dependency>

启动后访问

http://localhost:8080/swagger-ui.html

生成静态 JSON

curl http://localhost:8080/v3/api-docs > openapi.json

生成 HTML / PDF（可选）

npm install -g redoc-cli
redoc-cli build openapi.json -o api.html

二、Go（Gin / Echo 等）

使用 swaggo

go install github.com/swaggo/swag/cmd/swag@latest

项目中写注释

// @title My API
// @version 1.0
// @BasePath /api

生成文档

swag init

访问

http://localhost:8080/swagger/index.html

三、Python（FastAPI / Flask）

FastAPI（自带 Swagger）

from fastapi import FastAPI

app = FastAPI()

访问：

http://localhost:8000/docs

导出 OpenAPI：

http://localhost:8000/openapi.json

Flask + Flasgger

pip install flasgger

四、Node.js（Express）

npm install swagger-jsdoc swagger-ui-express

const swaggerUi = require('swagger-ui-express');
const swaggerDocs = require('./swagger');

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));

访问：

http://localhost:3000/api-docs

五、纯命令行生成静态文档（通用）

如果你已经有 openapi.yaml / json：

# 安装
npm install -g redoc-cli

# 生成 HTML
redoc-cli build openapi.yaml -o doc.html

# 生成 PDF
redoc-cli build openapi.yaml -o doc.pdf

六、常用命令汇总（Linux）

# 启动服务
java -jar app.jar

# 获取文档
curl http://localhost:8080/v3/api-docs > openapi.json

# 查看
xdg-open doc.html

七、你可以告诉我

✅ 用的是 什么语言 / 框架
✅ 想生成 网页 / PDF / 离线文档
✅ 是否需要 自动化 CI 生成

我可以直接给你可复制的完整示例。