---
slug: bruno-openapi-swagger-integration
status: published
title: Bruno 能跟 Swagger／OpenAPI 連動嗎？從匯入、同步到 CI/CD 的完整工作流
excerpt: Bruno 不只可以匯入 Swagger／OpenAPI，也能匯出 OpenAPI 3、連接遠端規格做 OpenAPI Sync，並透過 CLI 把規格轉成可執行的 API collection。
category: Developer Tools
tags: [Bruno, Swagger, OpenAPI, API testing, CI/CD, Git]
cover: "/static/bruno-openapi-swagger-integration-cover.png"
author: Seer
author_role: Author
read_time: 10 min
published_at: "2026-08-09T00:00:00Z"
updated_at: "2026-08-09T00:00:00Z"
---

## 先講結論：可以連動，但兩者定位不同

[Bruno](https://github.com/usebruno/bruno) 確實可以跟 Swagger / OpenAPI 搭配使用。而且以目前官方釋出的整合功能來看，已經不只是單純的「一次性匯入」而已：我們可以直接從 OpenAPI 規格書建立 Bruno collection、將現有的 collection 匯出成 OpenAPI 3，甚至能將 collection 連結到遠端的 OpenAPI/Swagger spec，透過 OpenAPI Sync 來比對差異並套用變更。

不過在開始動手前，要先釐清一個重要的觀念邊界：Bruno、Swagger UI 與 OpenAPI spec，這三者在架構上其實屬於不同層次：

- **OpenAPI／Swagger spec**：這是一份 API 規格書，用來定義路徑、HTTP Method、參數、Request Body、Response 以及安全性（Security）等合約內容。
- **Bruno**：這是一款在本機執行的 API 用戶端與測試工具（類似 Postman 或 Insomnia），用來建立、執行、撰寫腳本並測試 API 請求。
- **Swagger UI**：主要用來將 OpenAPI 文件渲染成網頁，提供視覺化的 API 瀏覽與操作介面。

因此，當我們問「Bruno 能不能跟 Swagger 連動」時，更精確的解釋是：

> Bruno 可以讀寫 OpenAPI 規格書，也能將規格書轉換成可執行的 API 請求集合（Collection）；它內建了類似 Swagger UI 的唯讀檢視畫面，但這並不代表 Bruno 會變成 Swagger UI，也不意味著你在 Bruno 內寫的測試腳本、斷言或本機設定，都能原封不動地同步回 OpenAPI 規格書中。

如果你的需求只是單純把後端產出的 `openapi.json` 轉換成可以直接點擊測試的 API 請求，Bruno 完全可以勝任。要是希望在 API 規格更新時自動收到變更通知，可以啟用 OpenAPI Sync。若是想反向從 Bruno collection 產生 API 文件，則能透過 OpenAPI 匯出功能，但匯出後通常建議再人工檢查一下規格是否完全精確。

## Bruno 是什麼？為什麼更適合納入 Git 管理？

Bruno 官方給它的定位是「專為探索與測試 API 設計的開源 IDE」，使用情境與 Postman 或 Insomnia 非常相似。它最大的特色在於，所有的 collection 都是直接以檔案形式存在本機的目錄中，且 request 是以純文字的 Bru 格式儲存。這對團隊協作非常友善，大家可以直接用 Git 來做版本控制。

這樣一來，API collection 就不必再被鎖在只能透過圖形介面（GUI）管理的雲端 workspace 裡。你可以把 API 請求、環境變數、資料夾結構、測試腳本等直接丟進專案 repo，透過 Pull Request（PR）進行 code review，並在 CI 流程中以 Bruno CLI 自動化執行。

雖然 Bruno 的 README 將產品定義為 "offline-only"，且長期規劃中不打算加入 cloud sync，但這和 OpenAPI 的 URL 匯入或 OpenAPI Sync 並不衝突。Bruno 可以讀取你指定的規格 URL，或者定期去檢查已連結的 spec，不過 collection 檔案本身依然是留在本機，並遵循 Git 的工作流程。

目前官方 repository 的最新 `main` commit 為 `a5b27e0`，官方 CLI 套件 `@usebruno/cli` 的版本則是 `1.16.0`，兩者皆採用 MIT 授權條款。由於軟體版本與官方文件會持續更新，以下整理的整合方式均以 2026-08-09 查核到的官方資料為準。

## Bruno × OpenAPI 整合地圖

| 需求 | 對應的 Bruno 功能 | 資料流向 | 適合情境 |
|---|---|---|---|
| 將 Swagger／OpenAPI 轉成實際請求 | OpenAPI 匯入 (Import) | OAS → Bruno collection | 後端規格已定，前端或 QA 想要快速點擊測試 API |
| 直接讀取遠端 API 規格 | URL 匯入 | URL → Bruno collection | 規格由開發伺服器、文件網站或公開端點提供 |
| 規格改版時比對差異 | OpenAPI Sync | 遠端 OAS ↔ 本機 collection 差異檢視 | API 規格持續更新，測試 collection 需要跟上變更 |
| 從現有請求產生規格文件 | OAS 匯出 (Export) | Bruno collection → OpenAPI 3 | 已整理好 collection，想產出 OpenAPI 3 交給其他工具 |
| 單純想看 OAS 規格 | OpenAPI 規格檢視 (Inspect Spec) | OAS → Bruno 唯讀檢視器 | 在 Bruno 內快速瀏覽 API 規格，不一定要建立請求 |
| 納入 CI/CD 自動化 | `bru import`、`bru run` | OAS → collection → CI 測試 | 規格更新後，自動重新產生並執行 API 測試 |
| 自行開發轉換工具 | `@usebruno/converters` | OAS 物件 → Bruno collection 物件 | 用於客製化產生器、內部工具或自動化工作流 |

從這張整合地圖也能看出「雙向同步」的界線：雖然 Bruno 同時支援 OAS 的匯入、匯出以及 OpenAPI Sync，但因為每個路徑保留的資料範疇不同，我們無法把它們直接當作無損的雙向自動同步。

## 第一條路：匯入 Swagger／OpenAPI 建立 Bruno collection

根據官方文件，目前 Bruno 支援匯入以下規格：

- OpenAPI 2.0 (即 Swagger 2.0)
- OpenAPI 3.x
- YAML 或 JSON 格式
- 本機的規格檔案
- 公開可存取的規格 URL

### GUI 匯入步驟

在 Bruno 介面中，可以從首頁的 **Import Collection**，或左上角的 **+** 選單啟動匯入。選擇 OpenAPI 後，可以直接拖曳 `.yaml` 或 `.json` 檔進去，也可以直接輸入 OpenAPI 的 URL。

Bruno 會根據規格書中的 endpoint 自動產生對應的 request。在匯入時，還能選擇資料夾的分類方式：

- **Tags**：預設模式，根據 OpenAPI 定義的 `tags` 將 endpoint 分配到各個功能資料夾中。
- **Paths**：根據 URL path 的結構來分組，例如把 `/api/v1/users` 與 `/api/v1/users/{id}` 整理在同一個層級。

如果 tag 的名稱中含有空白，Bru 格式會自動將空白轉換成底線（例如 `User Management` 會變成 `User_Management`）。官方文件也提到，如果想要完整保留原始的 tag 名稱，可以選擇使用 OpenCollection 的 YAML 格式。

必須特別注意的是，匯入並不是把 Swagger UI 的網頁畫面複製到 Bruno 中，而是將 OAS 定義的路徑與方法轉化為實際的 API request。這意味著匯入之後的 collection，你可以自由修改 URL、Header、Body 和認證資訊，甚至能為它們加上 Bruno 專屬的腳本（scripts）、斷言（assertions）與測試。

### CLI 匯入：更適合 CI 與專案自動化流程

如果你想透過指令將 OpenAPI 規格書轉換成 Bruno collection，可以使用 Bruno CLI。官方提供的指令如下：

```bash
npm install -g @usebruno/cli

bru import openapi \
  --source your-openapi.yaml \
  --output ./bruno-collection \
  --collection-name "Petstore API"
```

這會把指定的 OpenAPI 規格檔案轉換成指定輸出目錄下的 collection。CLI 目前預設會使用 OpenCollection layout，若團隊習慣使用經典的 `.bru` 檔案結構，則可以額外帶入參數：

```bash
bru import openapi \
  --source your-openapi.yaml \
  --output ./bruno-collection \
  --collection-name "Petstore API" \
  --collection-format=bru
```

其中 `--collection-format` 可設定為 `opencollection` 或 `bru`（預設為 `opencollection`）。`--source` 可以是本機檔案路徑或 URL，`--output` 是產出 collection 的目的地，`--collection-name` 則是 collection 的名稱。這些參數也提供了 `-s`、`-o`、`-n` 的簡寫。

另外，CLI 也支援直接輸出成單一 JSON 檔案的模式：

```bash
bru import openapi \
  --source your-openapi.yaml \
  --output-file ./generated/bruno-collection.json \
  --collection-name "Petstore API"
```

這種模式很適合放在 CI 流程中作為中間產物，再交給後續的自動化流程處理。不過要注意，單一 JSON 檔案的架構與 Bruno 平常以資料夾、Bru 或 OpenCollection YAML 來管理的工作流有些許不同，在導入前建議先評估 repo 打算追蹤哪一種格式。

### 透過 JavaScript Converter 進行客製化轉換

當 GUI 和 CLI 的預設格式無法滿足團隊需求時，官方也提供了 `@usebruno/converters` 套件。如果是 JSON 格式的 OAS，可以直接呼叫 `openApiToBruno` 來轉換：

```js
const { openApiToBruno } = require('@usebruno/converters');

const brunoCollection = openApiToBruno(openApiSpecification);
```

如果是 YAML 格式，則需要先透過 `yamlToJson` 轉成 JSON：

```js
const { openApiToBruno, yamlToJson } = require('@usebruno/converters');
const { readFile, writeFile } = require('fs/promises');

async function convertOpenApi(inputFile, outputFile) {
  const yamlContent = await readFile(inputFile, 'utf8');
  const openApiSpec = yamlToJson(yamlContent);
  const brunoCollection = openApiToBruno(openApiSpec);

  await writeFile(
    outputFile,
    JSON.stringify(brunoCollection, null, 2)
  );
}

convertOpenApi(
  './openapi.yaml',
  './generated/bruno-collection.json'
);
```

這種做法適合需要自訂檔名、資料夾結構或命名規則的內部工具。但請記得，這本質上仍只是規格書到 collection 的格式轉換，並不會自動替你的 API 邏輯進行語意審查。

## 第二條路：從 Bruno collection 匯出成 OpenAPI

如果你想反向將 Bruno collection 產生成 OAS，官方文件也有提供相應的匯出功能，目前明確支援輸出 **OpenAPI Specification V3**。

在 GUI 上的操作步驟如下：

1. 打開 Bruno 並點選你的 collection。
2. 點擊 collection 名稱旁的「三個點」選單（Context Menu）。
3. 選擇 **Share**。
4. 選擇匯出成 OpenAPI specification。

官方文件指出，順利匯出的前提是：你的 collection 必須擁有清晰的 request 結構、每個 endpoint 都有定義 HTTP Method，且已經設定好對應的 params 與 headers。

這個功能非常適合以下情境：

- 開發團隊習慣先在 Bruno 裡整理好測試通過的 requests，再交由其他工具產生文件。
- 手上只有 Bruno collection，需要產出一份基礎的 OpenAPI 3 規格來分享或做後續開發。
- 必須把本機的 API 操作流程串接到其他支援 OAS 規格的平台上。

然而，我們不能將「Bruno collection」與「OpenAPI spec」劃上等號。因為 Bruno collection 裡面通常還會包含許多專屬的內容：

- Pre-request scripts
- Post-response scripts
- Assertions 與 Tests
- 環境變數與本機的請求設定
- 為了測試而臨時調整的 Header、Body 範例或特定流程

這些資訊在 OpenAPI 中不一定能找到一對一的對應欄位。因此，匯出得到的 OAS 文件，建議還是要手動重新檢視 Path、Method、Parameters、Request Body、Responses 與 Security 等定義，不要直接拿去當作正式的 API 合約發布。

## 第三條路：OpenAPI Sync 到底是不是雙向同步？

在 Bruno 的官方文件中，有一頁獨立的 [OpenAPI Sync](https://docs.usebruno.com/open-api/openapi-sync) 介紹，而目前官方仍將此功能標記為 **OpenAPI (Beta)**。

它的核心功能是讓 Bruno collection 與遠端的 OpenAPI/Swagger spec 維持同步狀態。Bruno 會追蹤本機 collection 的變更，同時也會檢查遠端 spec 是否有更新。當兩邊產生落差時，你可以檢視差異並決定如何套用變更。

### 連接方式

官方文件提供了兩種啟動 OpenAPI Sync 的管道：

#### 針對現有的 Bruno collection

在現有 collection 的 context menu 中選擇 **OpenAPI (Beta)**，接著可以透過以下兩種方式連結規格書：

- **Add URL**：輸入遠端 OpenAPI spec 的 URL。
- **Upload file**：上傳本機的 OpenAPI spec 檔案。

#### 建立新的 collection

在透過 OpenAPI 匯入來新建 collection 的流程中，也可以直接開啟 OpenAPI Sync 功能。

這代表你不僅能在一次性匯入後手動進行同步，也可以讓已經手動維護一段時間的 Bruno collection 直接與指定的 spec 建立連結。

### Sync 與 Reset 的差別

當發現規格有落差時，OpenAPI Sync 並非直接以新版規格無腦覆蓋全部內容。官方文件將同步動作細分為以下兩種：

| 動作 | 行為 | 適合情境 |
|---|---|---|
| **Sync** | 根據 spec 調整 collection 的結構，但會保留你已經輸入的測試資料與變數 | API 規格更新了，但你希望保留已寫好的 Token、變數及實際測試內容 |
| **Reset** | 直接用 spec 的定義覆蓋單一 endpoint 的 URL、params、headers、body 與 auth | 本機的 request 與規格書落差太大，決定放棄本機的修改，完全跟隨規格 |

在執行 **Sync** 時，官方文件描述的具體保留行為包括：

- spec 中依然存在的 JSON body 欄位，會保留你本機填入的數值。
- spec 中新增的欄位，會使用規格書中的 example 或 default 值帶入。
- spec 中已移除的欄位，則會同步從 collection 中移除。
- `{{baseUrl}}`、`{{token}}` 等變數引用會維持原樣。
- 依然保留在 spec 中的 params 與 headers，其數值與啟用狀態（enabled/disabled）都會保留。
- Form body 的欄位也會比照上述規則處理。
- 在 auth mode 相同的情況下，OAuth2 的 URL、scope、grant type、API key 擺放位置、client credentials 以及相關變數引用都會被保留。如果 auth mode 改變，則會在 review 畫面中標示為變更項目。

**Reset** 的覆蓋力道雖然更強，但官方文件特別說明，它依然會保留你寫好的 tests、scripts 與 assertions。此外，不論是 Sync 還是 Reset，兩者都會保留請求的設定值（request settings）。最新版的 spec 也會下載並儲存在 collection 目錄底下的 `collection/resources/spec/`，因此在斷網的離線狀態下，你依然可以使用這些資料進行同步。

### OpenAPI Sync 會追蹤哪些變更？

官方文件指出，OpenAPI Sync 會比對的 collection 變更範圍僅限於：

- URL
- Params
- Headers
- Body

至於 Tests、scripts、assertions 與 request settings 則不會被納入 drift（差異）的比對中，只會予以保留。同樣地，若在相同的 auth mode 下修改了 token 的數值或 OAuth2 的 scope，也不會被判定為 spec drift，只有 auth mode 本身發生改變時，才會被列入變更。

這樣的設計相當符合實際的開發情境：讓 OpenAPI spec 專注於規範 API 合約，而 Bruno 則專注於測試資料與驗證邏輯。但這也代表，你不能指望它會幫你把 Bruno 裡所有的自訂腳本與測試跟 spec 進行全方位的 diff。

### 更新檢查頻率與方案限制

官方文件指出，OpenAPI Sync 預設每 5 分鐘會自動檢查一次遠端 spec 的更新，你也可以在連線設定中調整自動檢查的頻率或中斷 sync 連線。

另外必須注意的是，文件裡有提到方案限制：**Open Source 版本每月僅提供 5 次的 sync 次數**；若需要無限次的 sync 功能，則必須升級到 Bruno Pro 或 Ultimate 方案。這是屬於 OpenAPI Sync 功能的授權界線，與本機使用 Bruno CLI 來執行 collection 是兩碼子事。

## Bruno 內建的 Swagger UI 是什麼？

官方文件提到，在 Bruno 內可以透過一種類似 Swagger UI 的介面來檢視現有的 OAS，同時也支援在 Bruno 內直接建立與編輯 OAS 檔案。這讓 Bruno 也能兼作輕量級的 OpenAPI spec 編輯器與檢視工具。

不過，從 OpenAPI Sync 的 **Inspect Spec** 文件來看，這個介面本質上是一個「唯讀」的 SwaggerUI-like view。它的優點是讓你在開發時可以直接在 Bruno 內查看對齊的 spec，不需要另外開啟瀏覽器分頁；但它並不是一個能讓你部署到公開網路上的 Swagger UI 伺服器。

如果你的目的是：

- 對外部合作夥伴展示互動式 API 文件。
- 讓客戶端能直接在瀏覽器上發送測試請求。
- 架設一個公開的 API 文件站。

此時你仍然需要將 OpenAPI spec 交給專門的文件工具（如原生的 Swagger UI、Redoc 等）。Bruno 的定位更偏向工程師拿著規格書在開發環境產出請求、補齊測試、進行自動化驗證與追蹤規格變動。

## 如何在 Git 與 CI/CD 流程中搭配使用？

Bruno 官方的 README 中，直接將 CLI 定義為自動化測試與 CI/CD 的核心工具。最基本的安裝方式為：

```bash
npm install -g @usebruno/cli
```

安裝完後，你可以在 collection 目錄下執行整個 collection、單一 request 或是套用特定的環境變數：

```bash
# 執行整個 collection
bru run

# 執行單一 request
bru run request.bru

# 使用特定 environment 執行資料夾內的請求
bru run folder --env Local
```

官方也有提供 Bruno CLI 的 Docker image，可以在 Docker Hub 與 GitHub Container Registry 上找到。基本用法是將當前專案目錄掛載到容器內的 `/bruno` 目錄中：

```bash
docker run -v "$(pwd):/bruno" usebruno/cli run
```

根據開發流程，主要有以下三種常見的工作流搭配：

### 工作流 A：以 OpenAPI 為單一事實來源（Source of Truth）

如果你的團隊採用 API-first 或 code-first 的開發方式，建議這樣配置流程：

```text
後端程式碼／API 設計工具
  → 產出 openapi.yaml 或 openapi.json
  → 執行 bru import openapi
  → 產生或更新 Bruno collection
  → 人工在 Bruno 內補上環境變數、預處理腳本與測試斷言
  → 執行 bru run
  → CI 流程回報 API 測試狀態
```

在此模式中，OpenAPI 負責契約定義，Bruno collection 則是衍生出來的執行與測試層。當規格有變更時，建議透過 OpenAPI Sync 來檢視並套用變更，避免直接暴力覆蓋掉原本已經寫好的測試。

### 工作流 B：將 Bruno collection 作為主要工作檔

如果團隊習慣直接在 Bruno 中維護與測試請求，可以把 collection 檔案提交到 Git，讓大家直接在 Bru 檔案上改動請求內容與測試，流程如下：

```text
Bruno collection (存放於 Git 中進行 code review)
  → 執行 bru run 進行測試
  → 匯出為 OpenAPI 3
  → 發布至外部文件站或 API 管理平台
```

這適合快速迭代的產品，先有可執行的 API 測試後，再反向產出 OAS 當作規格起點。但要注意，匯出後仍然建議對產出的 OAS 進行人工校對。

### 工作流 C：規格書與 Collection 長期雙軌並行

如果規格書跟 Bruno collection 都會頻繁變動，建議團隊內部必須釐清變更權限：

| 團隊開發模式 | 建議的 Source of Truth | Bruno 在流程中扮演的角色 |
|---|---|---|
| API 規格統一由後端或設計工具定義 | OpenAPI 規格書 | 匯入規格、Sync 變更、補充測試、CI 執行 |
| API 處於探索階段，以真實請求為出發點 | Bruno Collection | 建立請求與驗證，穩定後再匯出成 OAS 規格 |
| 多個團隊需要共享同一份 API 規格 | 獨立的 OpenAPI Repo | 各團隊各自以 OpenAPI Sync 來同步自己的測試 collection |
| Bruno 內含有大量客製化的複雜測試邏輯 | OpenAPI + Bruno 雙層架構 | OAS 負責定義合約，Bruno 負責維護測試腳本與斷言 |

最容易遇到混亂的作法是：規格書由 A 改，Bruno collection 由 B 改，雙方沒有溝通就隨意執行匯入、匯出或 Sync。這會讓同步工具變成衝突的戰場，而非協作的助手。

## 與 Swagger／OpenAPI 連動時的限制與邊界

### 1. 「Swagger」並非單一工具

大家口中常說的「Swagger」可能代表 Swagger 2.0 規格、Swagger UI、Swagger Editor 或 SwaggerHub 雲端平台。Bruno 官方目前提供的整合主要圍繞在 OpenAPI 規格書的匯入、匯出與 Sync。雖然它支援 OpenAPI 2.0（Swagger 2.0）與 OpenAPI 3.x 規格的匯入，但本文查核到的官方文件未列出與各個 Swagger 雲端帳號或發佈平台的原生整合。

### 2. URL 匯入的存取權限限制

官方文件說明 URL 匯入功能時，前提是「公開可存取的 OpenAPI 規格 URL」（publicly accessible）。如果你的 spec 放在需要登入、連 VPN、內網，或需要帶入特殊 Authorization Header 的 API 端點上，可能無法直接使用此功能。遇到這種情況，建議先在 CI 或用本機 script 把檔案 fetch 下來，再以本機檔案進行匯入。

### 3. 匯入規格不等於自動建好測試案例

匯入 OpenAPI 規格只會幫你產生 API 的請求結構。至於 Response 斷言、跨 request 的 Token 傳遞、登入與登出流程、資料庫清理、重試機制等，依然需要在 Bruno 內手動撰寫腳本。規格書的 Response schema 只能協助描述資料結構，無法直接代替真實的 API 業務邏輯驗證。

### 4. OpenAPI Sync 並非全欄位比對

Sync 功能關注的範圍主要是 URL、Body、Params、Headers 與 Auth Mode。你寫在 Bruno 裡的 scripts、tests、assertions 與 request settings 都不會被納入 drift 差異比對，自然也不會因為 spec 改版而自動重新產生測試代碼。這主要是為了保護本機已寫好的測試內容不被覆蓋，在導入時需有此認知。

### 5. 匯出為 OpenAPI 3，不保證無損 round-trip

目前官方匯出功能明確定義為輸出 OpenAPI 3 (OAS V3)。若你當初是匯入 Swagger 2.0，經過 Bruno 再匯出，規格可能會被升級為 OpenAPI 3。雖然這可以當作升級格式的手段，但不能預期所有的擴充欄位（extensions）、自訂 security 寫法、schema 參照或 Bruno 專屬屬性都能在「匯入再匯出」的過程中毫無遺失。

### 6. Beta 狀態與免費版次數限制

OpenAPI Sync 目前在官方文件上仍標示為 Beta 階段，且 Open Source 版本有每月的同步次數限制。如果團隊每天都有大量的規格變更需要比對，建議先評估是否需要升級，或者改用 CI 指令搭配 `bru import` 產生暫時性的 collection，再利用 Git diff 來審查變更。

## 最推薦的導入步驟

與其一開始就將所有 collection 串上同步，建議按照以下階段循序漸進：

### 第一步：釐清並定義「誰是規格的源頭」

團隊必須先凝聚共識：到底是以 OpenAPI 規格書為準？還是以 Bruno 裡維護的 collection 為準？沒有定調這個前提，後續的匯入與匯出只會造成檔案互相覆蓋的慘劇。

### 第二步：挑選一支小規模的規格書進行測試

建議先找一份結構完整的 API spec，確認裡面包含：
- Tags 分類
- Path 與 Query parameters
- Request body
- Response schema
- Security scheme
- Example 或 Default 數值

匯入後，仔細檢查 Bruno 產生的 request 結構是否符合預期，並決定團隊要採用 Tags 還是 Paths 的分組方式。

### 第三步：補齊 Bruno 專屬的測試與變數

OpenAPI 負責定義合約，你則需要在 Bruno 內補足執行與驗證邏輯：
- 設置環境變數（environment variables）
- 設定運行時的認證參數（authentication runtime values）
- 撰寫 Pre-request / Post-response scripts
- 增加斷言（assertions）與測試
- 串接多個 Request 之間的參數傳遞
- 設定 CI 測試的報告格式（reporter）與失敗判定

### 第四步：啟用 OpenAPI Sync 進行比對

當單次匯入測試無誤後，再開啟與遠端規格書的 OpenAPI Sync。在執行第一次同步時，務必仔細檢視 review 視窗中的 diff 差異，不要直接點選全部套用。特別注意 Auth Mode、被移除的 Body 欄位以及 Path/Header 的改變，這些都會直接影響到測試請求是否能順利發送。

### 第五步：將 `bru run` 納入 CI/CD

最後，將測試 collection 納入 CI 流程中，並決定當規格更新時的應對策略：
- 方案一：每次都重新 import 產生新 collection，並用 Git diff 來審查變更。
- 方案二：由開發者在本地透過 OpenAPI Sync 手動 review並更新後再送 PR。
- 方案三：維護一份固定的測試 collection，只有當 spec 變更通過 PR 審查後，才同步修改測試檔。

## 結語：Bruno 是 OpenAPI 的執行層，而非 Swagger UI 的代替品

Bruno 與 Swagger / OpenAPI 的連動方案相當完整，不僅僅是一次性的匯入：

- **GUI 介面**：支援從檔案或 URL 直接匯入 OpenAPI 2.0 / 3.x 規格。
- **CLI 工具**：提供 `bru import openapi` 指令，便於在專案或 CI 中自動產生 collection。
- **@usebruno/converters**：讓團隊能靈活自訂轉換規則。
- **規格匯出**：能將現有 collection 匯出成標準的 OpenAPI 3 格式。
- **OpenAPI Sync**：在不影響本機測試腳本的前提下，追蹤規格變更並選擇性套用差異。
- **自動化測試**：透過 Bruno CLI 與 Docker 輕鬆將測試流程搬上 CI/CD。

兩者的關係可以總結為：

> **OpenAPI 負責描述合約（API Contract），而 Bruno 則負責將合約落地，變成可執行、可撰寫腳本、可測試且能納入 Git 管理的 API 工作流。**

如果你需要的是公開的互動式 API 文件，請繼續使用 Swagger UI 或其他文件站工具；但如果你的目標是將規格轉換成實際請求、管理多套環境、編寫測試與執行 CI 驗證，那麼 Bruno 就可以作為承接 OpenAPI 規格的執行工具。在雙向維護時，也應將 OpenAPI Sync 視為「輔助檢查與手動確認」的工具，而非完全無腦的雙向同步通道。

## 官方來源與查核範圍

- [Bruno 官方 repository](https://github.com/usebruno/bruno)：產品定位、檔案儲存、Git 工作流、CLI 與 Docker 支援。
- [Bruno `readme.md`](https://github.com/usebruno/bruno/blob/main/readme.md)：offline-only 定位說明、Bru 格式介紹、CLI 語法、`bru run` 與 Docker 指令。
- [Bruno repository metadata](https://api.github.com/repos/usebruno/bruno)：確認採用 MIT 授權、預設分支、查核時之 main commit 狀態。
- [Bruno CLI `package.json`](https://raw.githubusercontent.com/usebruno/bruno/main/packages/bruno-cli/package.json)：驗證 `@usebruno/cli` 版本、`bru` 執行檔與相關依賴。
- [OpenAPI and Bruno](https://docs.usebruno.com/open-api/overview)：確認支援 OpenAPI 2.0 / Swagger 2.0、OpenAPI 3.x 的匯入與匯出功能總覽。
- [Import OpenAPI Specification](https://docs.usebruno.com/open-api/importOAS)：確認支援檔案/URL 匯入、YAML/JSON 格式，以及 tags/paths 的分組設定。
- [Export to OpenAPI Specification](https://docs.usebruno.com/open-api/exportOAS)：確認 collection 可匯出為 OAS V3。
- [OpenAPI Sync](https://docs.usebruno.com/open-api/openapi-sync)：Beta 狀態確認、連線方式、Sync / Reset 行為差異、比對範圍、保留欄位、自動更新檢查機制與免費版次數限制。
- [Bruno CLI Import Data](https://docs.usebruno.com/bru-cli/import)：`bru import openapi` 指令參數、OpenCollection 與經典 `.bru` 格式、單一 JSON 匯出格式。
- [OpenAPI to Bruno converter](https://docs.usebruno.com/converters/openapi-to-bruno)：`@usebruno/converters` 模組中 `openApiToBruno` 與 `yamlToJson` 的使用方式。
- [Create OpenAPI Specification](https://docs.usebruno.com/open-api/createOAS)：確認 Bruno 內建的 OAS 唯讀檢視、建立與編輯器功能。

本文查核日期：2026-08-09。官方 repository 以持續更新的 `main` 分支為主；軟體版本、文件說明、Beta 狀態與方案限制可能隨時間有所調整。本文未於本機安裝或實際執行 Bruno repository 專案，所有 CLI 指令與功能細節均來自官方 README、套件 metadata 與官方說明文件。