怎么生成linux swagger文档

在 Linux 环境下生成 Swagger 文档，常见做法取决于你使用的技术栈。下面按最主流的场景给你一个清晰、可操作的指南。

一、最常见：基于 OpenAPI（Swagger）规范生成文档

✅ 方式 1：代码中直接写 Swagger 注解（推荐）

1️⃣ Java（Spring Boot）

最常用方案：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

生成静态文档（Linux 命令行）

npx @redocly/cli build-docs openapi.json -o swagger.html

✅ 方式 2：手写 OpenAPI YAML / JSON

适合：

• Go
• Python
• Node.js
• 微服务

示例 openapi.yaml

openapi: 3.0.3
info:
  title: User API
  version: 1.0.0
paths:
  /users:
    get:
      summary: 获取用户列表
      responses:
        '200':
          description: OK

在 Linux 生成 HTML

npm install -g @redocly/cli
redocly build-docs openapi.yaml -o swagger.html

二、Go 项目生成 Swagger

使用 swaggo

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

代码中写注解

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

生成

swag init

生成：

docs/docs.swagger.json

访问：

/swagger/index.html

三、Python（FastAPI / Flask）

FastAPI（自带 Swagger）

from fastapi import FastAPI

app = FastAPI()

访问：

http://localhost:8000/docs

导出：

http://localhost:8000/openapi.json

四、Linux 下常用 Swagger 工具汇总

五、你适合哪种？

你可以告诉我：

1. 使用什么语言？（Java / Go / Python / Node）
2. 是否已有接口代码？
3. 想要 网页文档 还是 离线 PDF/HTML？

我可以直接给你一步步命令级教程。