debian swagger怎么生成文档

在 Debian 上“用 Swagger 生成接口文档”通常有两种常见场景：

1. 代码里写注解，自动生成 Swagger/OpenAPI 文档（最常用）
2. 已有 API，用 Swagger 工具生成静态文档（HTML / JSON / YAML）

下面按语言和你可能的使用方式说明。

一、Java（Spring Boot）生成 Swagger 文档（最常见）

1. 安装基础环境（Debian）

sudo apt update
sudo apt install openjdk-17-jdk maven -y

2. 引入 Swagger / Springdoc

推荐用 Springdoc（Swagger 3 / OpenAPI）

pom.xml：

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

3. 启动项目

mvn spring-boot:run

4. 访问文档

• Swagger UI

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

• OpenAPI JSON

  http://localhost:8080/v3/api-docs
  

二、Python（FastAPI / Flask）生成 Swagger

FastAPI（自带 Swagger）

pip install fastapi uvicorn

from fastapi import FastAPI

app = FastAPI()

@app.get("/items")
def read_items():
    return {"msg": "hello"}

启动：

uvicorn main:app --reload

访问：

http://127.0.0.1:8000/docs

三、用 Swagger Codegen / CLI 生成静态文档

1. 安装 Swagger CLI（Debian）

sudo apt install default-jre -y
wget https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.41/swagger-codegen-cli-3.0.41.jar

2. 生成 HTML 文档

java -jar swagger-codegen-cli-3.0.41.jar generate \
  -i api.yaml \
  -l html2 \
  -o docs

3. 生成客户端 / 服务端代码

java -jar swagger-codegen-cli.jar generate \
  -i api.yaml \
  -l spring \
  -o spring-server

四、用 swagger-ui 单独部署文档（Debian）

sudo apt install nginx -y
git clone https://github.com/swagger-api/swagger-ui.git
cp -r swagger-ui/dist /var/www/swagger

配置 Nginx：

server {
    listen 80;
    root /var/www/swagger;
    index index.html;
}

五、常见坑提醒

• Spring Boot 3 + Swagger 2 不兼容（用 springdoc）
• 安全框架要放行 /v3/api-docs
• 生产环境建议关闭 Swagger UI

如果你能告诉我：

• 用的语言（Java / Python / Go / Node）
• 是否是 Spring Boot
• 想生成 UI 文档 还是 离线 HTML

我可以给你更精确的 Debian 操作步骤。