1. 首页
  2. 新手教程
  3. Swagger API 文档

搬瓦工 VPS 搭建 Swagger API 文档自动生成教程

Swagger（现更名为 OpenAPI）是 API 文档领域的行业标准，它通过结构化的规范描述 RESTful API 接口，并提供交互式的文档界面供开发者浏览和测试 API。良好的 API 文档是团队协作和对外开放的基础。本教程将介绍如何在搬瓦工 VPS 上部署 Swagger UI 文档服务，编写 OpenAPI 规范，并集成到不同语言的后端项目中实现文档自动生成。部署前请确保已安装好 Docker 和 Docker Compose。

一、OpenAPI 与 Swagger 概述

  • OpenAPI Specification：用 YAML 或 JSON 格式描述 API 接口的标准规范，目前主流版本为 3.1。
  • Swagger UI：交互式 API 文档界面，可以直接在浏览器中测试 API。
  • Swagger Editor：在线编辑 OpenAPI 规范的可视化编辑器。
  • Swagger Codegen：根据 OpenAPI 规范自动生成客户端 SDK 和服务端框架代码。

二、Docker 部署 Swagger UI

2.1 创建项目目录

mkdir -p /opt/swagger && cd /opt/swagger
mkdir -p specs

2.2 编写 OpenAPI 规范文件

cat > specs/api.yaml <<'EOF'
openapi: 3.1.0
info:
  title: 示例 API 服务
  description: |
    这是一个完整的 API 文档示例，展示了用户管理和文章管理的接口定义。
    支持 Bearer Token 认证。
  version: 2.0.0
  contact:
    name: API 支持团队
    email: api-support@example.com

servers:
  - url: https://api.example.com/v2
    description: 生产环境
  - url: https://staging-api.example.com/v2
    description: 测试环境

security:
  - BearerAuth: []

paths:
  /users:
    get:
      summary: 获取用户列表
      tags: [用户管理]
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: 成功返回用户列表
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  total:
                    type: integer
    post:
      summary: 创建新用户
      tags: [用户管理]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUser'
      responses:
        '201':
          description: 用户创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /users/{id}:
    get:
      summary: 获取单个用户详情
      tags: [用户管理]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 成功返回用户详情
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: 用户不存在

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
          format: email
        role:
          type: string
          enum: [admin, user, editor]
        createdAt:
          type: string
          format: date-time

    CreateUser:
      type: object
      required: [name, email]
      properties:
        name:
          type: string
          minLength: 2
          maxLength: 50
        email:
          type: string
          format: email
        role:
          type: string
          enum: [admin, user, editor]
          default: user

    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
EOF

2.3 Docker Compose 部署

cat > docker-compose.yml <<'EOF'
version: '3.8'

services:
  swagger-ui:
    image: swaggerapi/swagger-ui:latest
    container_name: swagger-ui
    restart: always
    ports:
      - "127.0.0.1:8082:8080"
    environment:
      SWAGGER_JSON: /specs/api.yaml
      BASE_URL: /docs
      DOC_EXPANSION: list
      DEEP_LINKING: "true"
      DISPLAY_REQUEST_DURATION: "true"
    volumes:
      - ./specs:/specs:ro

  swagger-editor:
    image: swaggerapi/swagger-editor:latest
    container_name: swagger-editor
    restart: always
    ports:
      - "127.0.0.1:8083:8080"

volumes: {}
EOF

docker compose up -d

三、Nginx 反向代理

cat > /etc/nginx/conf.d/swagger.conf <<'EOF'
server {
    listen 443 ssl http2;
    server_name docs.example.com;

    ssl_certificate /etc/letsencrypt/live/docs.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/docs.example.com/privkey.pem;

    # Swagger UI
    location /docs {
        proxy_pass http://127.0.0.1:8082;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # Swagger Editor
    location /editor {
        proxy_pass http://127.0.0.1:8083;
        proxy_set_header Host $host;

        # 添加基本认证保护编辑器
        auth_basic "Swagger Editor";
        auth_basic_user_file /etc/nginx/.htpasswd;
    }
}
EOF

nginx -t && systemctl reload nginx

四、Python FastAPI 集成

FastAPI 框架内置 OpenAPI 文档生成能力：

pip install fastapi uvicorn

cat > app.py <<'EOF'
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, EmailStr

app = FastAPI(
    title="用户管理 API",
    description="完整的用户管理接口文档",
    version="2.0.0",
    docs_url="/docs",        # Swagger UI 地址
    redoc_url="/redoc",      # ReDoc 地址
    openapi_url="/openapi.json"
)

class UserCreate(BaseModel):
    name: str
    email: EmailStr
    age: int | None = None

class UserResponse(BaseModel):
    id: int
    name: str
    email: str

@app.post("/users", response_model=UserResponse, tags=["用户管理"])
async def create_user(user: UserCreate):
    """创建新用户，返回用户信息和ID。"""
    return {"id": 1, "name": user.name, "email": user.email}

@app.get("/users/{user_id}", response_model=UserResponse, tags=["用户管理"])
async def get_user(user_id: int):
    """根据用户ID获取用户详情。"""
    return {"id": user_id, "name": "Alice", "email": "alice@example.com"}
EOF

uvicorn app:app --host 0.0.0.0 --port 8000

五、Go Gin + Swag 集成

# 安装 swag CLI
go install github.com/swaggo/swag/cmd/swag@latest

# 在 Go 项目中添加注释
# 然后运行生成命令
swag init -g main.go -o docs/

# 在 Gin 路由中注册 Swagger
# import swaggerFiles "github.com/swaggo/files"
# import ginSwagger "github.com/swaggo/gin-swagger"
# r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

六、文档版本管理

# 多版本 API 文档管理目录结构
mkdir -p specs/v1 specs/v2

# 在 Swagger UI 中配置多版本
# docker-compose.yml 环境变量
# URLS: "[{url: '/specs/v1/api.yaml', name: 'V1'}, {url: '/specs/v2/api.yaml', name: 'V2'}]"

七、自动生成客户端 SDK

# 使用 OpenAPI Generator 生成客户端代码
docker run --rm -v /opt/swagger/specs:/specs \
  openapitools/openapi-generator-cli generate \
  -i /specs/api.yaml \
  -g python \
  -o /specs/sdk/python

# 支持的语言包括：python, javascript, typescript, go, java, ruby, php 等

八、常见问题

CORS 跨域问题

如果 Swagger UI 和 API 不在同一个域名下，需要在 API 服务端配置 CORS 响应头。

规范验证失败

# 使用在线验证工具或 CLI 验证规范文件
docker run --rm -v /opt/swagger/specs:/specs \
  openapitools/openapi-generator-cli validate \
  -i /specs/api.yaml

总结

Swagger/OpenAPI 是 API 文档管理的标准工具链。配合 Postman 测试可以建立完整的 API 开发和测试工作流。选购搬瓦工 VPS 请参考 全部方案，购买时使用优惠码 NODESEEK2026 可享受 6.77% 的折扣，购买链接：bwh81.net。

关于本站

搬瓦工VPS中文网（bwgvps.com）是非官方中文信息站，整理搬瓦工的方案、优惠和教程。我们不销售主机，不提供技术服务。

新手必读
搬瓦工优惠码

NODESEEK2026（优惠 6.77%）

购买时填入即可抵扣。