learnNote

主题

02 · 安装与第一次启动 Swagger UI / Editor ​

生活类比：拿到一份"菜单设计稿"（openapi.yaml），怎么把它贴到墙上让顾客看？这就是 Swagger UI 的工作。Swagger Editor 就像 Figma，让你在一边设计、一边预览。

1. 全家桶都装啥？四大工具一图看懂 ​

┌──────────────────────────────────────────────────────────┐
│  Swagger Editor   →  写 yaml + 实时预览                    │
│  Swagger UI       →  把 yaml 渲染成漂亮的在线文档           │
│  Swagger Codegen  →  老牌代码生成器（已停止维护，了解即可）  │
│  openapi-generator→  Codegen 社区分支，目前主流（第 8 章）  │
└──────────────────────────────────────────────────────────┘
工具干啥推荐度
Swagger Editor学习时写 yaml，左边代码、右边渲染⭐⭐⭐⭐⭐
Swagger UI给团队/外部展示 API 文档⭐⭐⭐⭐⭐
RedocSwagger UI 的"加强版"，更漂亮 + 适合长文档⭐⭐⭐⭐
Stoplight Studio桌面客户端，可视化拖拽编辑⭐⭐⭐
Apifox / Apipost国产，把 Swagger / Postman / Mock 一锅端⭐⭐⭐⭐

2. 完全不安装 · 在线版（5 秒上手） ​

最简单的入门方式：打开浏览器。

工具在线地址
Swagger Editorhttps://editor.swagger.io
Swagger UI 官方demohttps://petstore.swagger.io
Redoc 在线https://redocly.github.io/redoc/

推荐：先打开 Swagger Editor，左边自带"Petstore"示例（小宠物店 API），改两个字段就能看到右边变化，立即建立直觉。

3. 本地版 · Docker 一句话起（推荐） ​

前置：装好 Docker 即可，没装的去 docker.com 下个 Desktop。

3.1 起一个 Swagger UI（看自己的 yaml） ​

bash
docker run -d \
  --name swagger-ui \
  -p 8080:8080 \
  -e SWAGGER_JSON=/spec/openapi.yaml \
  -v $PWD/openapi.yaml:/spec/openapi.yaml \
  swaggerapi/swagger-ui

打开 http://localhost:8080 → 看到自己的 yaml 渲染出的文档。

⚠️ Windows PowerShell 把 $PWD 换成 ${PWD}，CMD 换成 %cd%。

3.2 起一个 Swagger Editor（在线编辑） ​

bash
docker run -d --name swagger-editor -p 8081:8080 swaggerapi/swagger-editor

打开 http://localhost:8081 → 跟在线版一模一样，但完全本地，可以编辑保存。

3.3 起一个 Mock 服务（Prism）—— 第 8 章详细讲，先记住 ​

bash
docker run --rm -p 4010:4010 \
  -v $PWD:/spec \
  stoplight/prism:4 mock -h 0.0.0.0 /spec/openapi.yaml

curl http://localhost:4010/users → 返回 yaml 里定义的示例数据。这是前端在后端没写完时的救命神器。

3.4 docker-compose 一键起（推荐） ​

yaml
# docker-compose.yml
version: '3.8'
services:
  ui:
    image: swaggerapi/swagger-ui
    ports: ["8080:8080"]
    environment:
      SWAGGER_JSON: /spec/openapi.yaml
    volumes:
      - ./openapi.yaml:/spec/openapi.yaml

  editor:
    image: swaggerapi/swagger-editor
    ports: ["8081:8080"]

  mock:
    image: stoplight/prism:4
    ports: ["4010:4010"]
    command: mock -h 0.0.0.0 /spec/openapi.yaml
    volumes:
      - ./openapi.yaml:/spec/openapi.yaml
bash
docker compose up -d

✅ 一句话拿到：在线文档 (8080) + 编辑器 (8081) + Mock 服务 (4010)。

4. 不用 Docker · 直接用 npm ​

4.1 swagger-ui (静态资源) ​

最简单的本地预览：

bash
npm i -g http-server
git clone https://github.com/swagger-api/swagger-ui.git
cd swagger-ui/dist
http-server -p 8080

或者直接用 swagger-ui-dist 这个 npm 包，把 dist/ 拷到自己项目静态目录。

4.2 redoc-cli · 一行命令生成单页文档 ​

bash
npx @redocly/cli build-docs openapi.yaml -o api.html

得到一个独立的 api.html，扔到任何静态服务器都能用——特别适合作为发布物。

5. 嵌入到自己的项目 · 三种姿势 ​

5.1 SPA 项目里嵌一个 Swagger UI 路由 ​

bash
npm i swagger-ui-react
jsx
// React
import 'swagger-ui-react/swagger-ui.css';
import SwaggerUI from 'swagger-ui-react';

export default function ApiDoc() {
  return <SwaggerUI url="/openapi.yaml" />;
}
vue
<!-- Vue 3：可以装 swagger-ui 包，自己挂 div -->
<template><div id="swagger" /></template>
<script setup>
import SwaggerUIBundle from 'swagger-ui';
import 'swagger-ui/dist/swagger-ui.css';
import { onMounted } from 'vue';
onMounted(() => {
  SwaggerUIBundle({ url: '/openapi.yaml', dom_id: '#swagger' });
});
</script>

5.2 后端框架内置（第 9 章详细讲） ​

框架嵌入方式默认地址
Spring Bootspringdoc-openapi-starter-webmvc-ui/swagger-ui.html
Expressswagger-ui-express自定义路由 /api-docs
NestJS@nestjs/swagger/api
FastAPI内置！什么都不用装/docs 或 /redoc
Go (gin)gin-swagger/swagger/index.html
Django RESTdrf-yasg 或 drf-spectacular/swagger/

5.3 静态托管（生产推荐） ​

打包阶段把 yaml 转成单页 HTML，扔到 OSS / Nginx / GitHub Pages：

bash
npx @redocly/cli build-docs openapi.yaml -o public/api.html
# 然后部署 public/ 到任何静态服务器

6. 第一份能跑的 openapi.yaml ​

把下面内容存为 openapi.yaml，然后用上面任意方式打开：

yaml
openapi: 3.0.3
info:
  title: 我的第一个 API
  description: 一个简单的"打招呼"接口
  version: 1.0.0

servers:
  - url: http://localhost:3000
    description: 本地

paths:
  /hello:
    get:
      summary: 打招呼
      parameters:
        - name: name
          in: query
          required: false
          schema:
            type: string
            default: World
          description: 你想被怎么叫
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Hello, World!"

打开 Swagger UI / Editor，你应该看到：

  • 一个绿色的 GET /hello 折叠条
  • 展开后能看到 name 参数表单
  • 点击 Try it out 可以模拟请求（如果搭配 Mock 服务，能拿到真实响应）

7. 常见坑 & 解决方案 ​

7.1 Swagger UI 打开是空白页 ​

最常见的原因是跨域：

Failed to load API definition.
Fetch error
Possible cross-origin (CORS) issue.

解决：

  • 把 yaml 放到 Swagger UI 同源的目录
  • 或者给 yaml 文件所在服务加 Access-Control-Allow-Origin: *
  • 或者用 Docker 启动时 -v $PWD/openapi.yaml:/usr/share/nginx/html/openapi.yaml 把 yaml 直接放进 UI 容器

7.2 yaml 里 $ref 报错 "Could not resolve reference" ​

通常是 路径写错 或 跨文件 ref 没加 base URL：

yaml
# 错
$ref: 'User'

# 对
$ref: '#/components/schemas/User'

# 跨文件 ref
$ref: './schemas/user.yaml#/User'

7.3 中文乱码 ​

yaml 文件保存为 UTF-8 无 BOM 即可。VS Code 默认 UTF-8，没问题。

7.4 Try it out 没反应 / CORS ​

Try it out 实际是浏览器从你电脑发请求到 servers.url。如果后端没开 CORS，浏览器会拒绝。两种解法：

  • 后端临时加 Access-Control-Allow-Origin: *
  • 前面挂个 Nginx 反代（参考 nginx 篇 05 章）

8. 各工具速查表 ​

场景推荐工具
学 Swagger 写 yamlSwagger Editor 在线版
给团队展示文档Swagger UI + Docker
给客户/外部用户展示Redoc (更漂亮)
不熟 yaml 想拖拽Stoplight Studio / Apifox
国内团队 + 想把 Postman 也整合Apifox
一份 yaml 多个产物（SDK/Mock）openapi-generator + Prism

9. 章末面试题速览 ​

  1. Swagger UI 和 Swagger Editor 的区别？ → UI 是"展示器"（只读），Editor 是"编辑器"（可改可预览）。
  2. 想给前端文档加 Try it out 但请求跨域怎么办？ → 后端开 CORS，或前面挂 Nginx 反向代理同源。
  3. Swagger UI 和 Redoc 怎么选？ → 内部团队 / 调试用 UI（带 Try it out）；外部展示 / 文档发布用 Redoc（更漂亮、长文档体验更好）。

🎬 可视化演示 ​

下方 demo 模拟"三种部署方式"：在线版、Docker 本地、嵌入项目，让你直观看到一份 yaml 是如何变成在线文档的。

→ 打开 02_install/demo.html

🎬 可视化演示 ​

演示加载缓慢或样式异常？点此在新标签页打开 ↗