Bruno를 사용 중이라면 장점은 분명합니다. 컬렉션이 Git 리포지토리의 일반 .bru 파일로 저장되고, 코드와 함께 버전 관리되며, 클라우드 계정 없이도 오프라인 우선 방식으로 API 요청을 관리할 수 있습니다.
하지만 팀 협업이 시작되면 곧 이런 질문을 받게 됩니다. “문서는 어디에 있나요? 링크로 공유할 수 있나요?” Bruno는 API 요청을 작성하고 실행하는 데 강점이 있지만, 공유 가능한 문서 포털을 게시하는 도구는 아닙니다. 이 글에서는 Bruno로 API 문서를 다룰 때 가능한 것과 한계를 정리하고, OpenAPI 사양(spec)을 기반으로 실제 공유 가능한 문서 URL을 만드는 방법을 설명합니다.
팀이 API 문서에서 실제로 필요로 하는 것
API 문서는 단순한 엔드포인트 목록이 아닙니다. 실제 개발 워크플로에서는 보통 다음 세 가지가 필요합니다.
공유 가능한 URL
프론트엔드 개발자, QA, 파트너가 리포지토리를 클론하거나 API 클라이언트를 설치하지 않고도 문서를 읽을 수 있어야 합니다.API와 동기화된 내용
실제 API와 다른 문서는 오히려 위험합니다. 문서는 코드 또는 API 사양(spec) 변경을 따라가야 합니다.대화형 “직접 해보기(try it)” 기능
인증 정보, 헤더, 쿼리 파라미터, 요청 본문을 입력하고 문서 안에서 실제 요청을 실행할 수 있어야 합니다.
이 세 가지가 충족되면 문서는 팀의 단일 정보원이 됩니다. 하나라도 빠지면 개발자는 다시 Slack, 이슈, PR 댓글에서 API 사용법을 물어보게 됩니다.
Bruno에서 가능한 문서화
Bruno는 내부 개발자용 문서화에는 꽤 유용합니다.
Bruno 컬렉션은 사람이 읽을 수 있는 .bru 파일로 저장됩니다. 예를 들어 요청 파일을 열면 메서드, URL, 헤더, 본문을 확인할 수 있습니다.
meta {
name: Get User
type: http
}
get {
url: {{baseUrl}}/users/{{userId}}
body: none
auth: none
}
headers {
Authorization: Bearer {{token}}
}
또한 Bruno는 요청별 docs 블록과 앱 내 마크다운 문서 보기를 지원합니다. 따라서 엔드포인트 설명, 사용 조건, 예시 등을 요청과 함께 관리할 수 있습니다.
docs {
# Get User
특정 사용자 정보를 조회합니다.
- `userId`: 조회할 사용자 ID
- 인증 필요
}
이 방식의 장점은 명확합니다.
- 문서가 Git에 저장됩니다.
- PR에서 요청 변경과 문서 변경을 함께 리뷰할 수 있습니다.
- API 클라이언트 안에서 요청과 설명을 같이 볼 수 있습니다.
하지만 문제는 게시(publishing) 입니다.
Bruno에는 컬렉션을 공개 문서 사이트로 변환해 주는 내장 기능이 없습니다. 안정적인 URL, 사용자 지정 도메인, 외부 사용자를 위한 웹 문서 포털을 자동 생성하는 “Publish” 버튼이 없습니다.
즉, Bruno 앱을 설치하고 컬렉션을 클론한 사람은 문서를 볼 수 있지만, API 소비자에게 바로 전달할 수 있는 문서 링크는 만들기 어렵습니다.
Bruno 문서를 공개하려고 할 때 흔한 우회 방법
팀들은 보통 다음 중 하나를 선택합니다.
- Bruno 컬렉션을 OpenAPI로 변환
- OpenAPI 파일을 정적 문서 생성기에 연결
- CI에서 문서 사이트 빌드
- 별도 호스팅 환경에 배포
- README를 수동으로 유지
예를 들어 다음과 같은 구조를 만들 수 있습니다.
api-docs/
├── openapi.yaml
├── docs/
├── package.json
└── .github/
└── workflows/
└── publish-docs.yml
이 방식은 작동할 수 있습니다. 하지만 유지해야 할 것이 늘어납니다.
- OpenAPI 파일
- 문서 생성 도구
- CI/CD 파이프라인
- 호스팅 설정
- 수동 README 또는 가이드 문서
결국 문서는 API 요청을 테스트하는 도구의 일급 산출물이 아니라 별도 프로젝트가 됩니다.
코드로서의 문서(docs-as-code) 원칙
더 안정적인 접근은 문서를 별도의 수동 산출물이 아니라 API 사양(spec)의 결과물로 취급하는 것입니다.
코드로서의 문서 워크플로(docs-as-code workflow)에서는 보통 API를 OpenAPI 같은 기계가 읽을 수 있는 사양으로 정의합니다.
예시는 다음과 같습니다.
openapi: 3.0.3
info:
title: User API
version: 1.0.0
paths:
/users/{userId}:
get:
summary: 사용자 조회
parameters:
- name: userId
in: path
required: true
schema:
type: string
responses:
"200":
description: 사용자 정보
content:
application/json:
schema:
type: object
properties:
id:
type: string
name:
type: string
이 사양은 Git에 저장하고 PR에서 리뷰할 수 있습니다. 그리고 같은 사양으로 다음을 생성할 수 있습니다.
- API 문서
- 목 서버
- 테스트 케이스
- 클라이언트 SDK
- 타입 정의
핵심은 문서를 따로 “업데이트해야 하는 작업”으로 두지 않는 것입니다. 사양이 변경되면 문서도 그 사양을 기준으로 렌더링됩니다.
사양(spec)에서 문서를 생성하고 호스팅하기
이 지점에서 Apidog를 사용할 수 있습니다. Apidog는 OpenAPI 사양을 기반으로 대화형 호스팅 문서 사이트를 생성합니다.
OpenAPI 사양을 Apidog에 가져오면 문서 포털이 생성됩니다. 이 문서는 다음과 같은 형태로 사용할 수 있습니다.
- 공유 가능한 URL로 호스팅
- 사용자 지정 도메인 연결 가능
- 문서 안에서 “직접 해보기(try it)” 요청 실행
- 사양에 정의된 파라미터, 헤더, 인증, 요청 본문 반영
- 수동 복사본이 아니라 API 사양 기반으로 생성
즉, 문서를 위한 별도 정적 사이트 파이프라인을 직접 구성하지 않아도 됩니다.
구현 단계: OpenAPI 사양에서 공유 가능한 문서 URL 만들기
OpenAPI 사양이 있다면 다음 순서로 진행할 수 있습니다.
| 단계 | 작업 | 결과 |
|---|---|---|
| 1 | OpenAPI 사양을 준비합니다. | 엔드포인트, 스키마, 예시가 문서 생성의 기준이 됩니다. |
| 2 | Apidog에 사양을 가져오거나 작성합니다. | API 구조가 프로젝트에 반영됩니다. |
| 3 | 문서 설정을 엽니다. | 문서 공개 범위와 표시 방식을 구성할 수 있습니다. |
| 4 | 공개, 비공개, 비밀번호 보호 등 가시성을 선택합니다. | 소비자 접근 범위를 제어할 수 있습니다. |
| 5 | 필요하면 사용자 지정 도메인을 연결합니다. |
docs.yourcompany.com 같은 주소로 문서를 제공할 수 있습니다. |
| 6 | 게시합니다. | 공유 가능한 문서 URL이 생성됩니다. |
| 7 | 팀 또는 외부 소비자에게 링크를 전달합니다. | 별도 설치 없이 문서를 읽고 요청을 실행할 수 있습니다. |
Bruno 컬렉션을 사용 중이라면
이미 Bruno 컬렉션을 운영하고 있다면 바로 버릴 필요는 없습니다. 일반적인 흐름은 다음과 같습니다.
Bruno collection
↓
OpenAPI spec
↓
Hosted API documentation
실무에서는 다음 순서로 접근할 수 있습니다.
- Bruno 컬렉션을 정리합니다.
- 요청 URL, 메서드, 헤더, 본문, 예시를 확인합니다.
- OpenAPI 사양으로 변환합니다.
- 변환된 사양을 Git에서 관리합니다.
- 해당 사양을 Apidog에 가져옵니다.
- 문서를 게시하고 URL을 공유합니다.
중요한 점은 문서의 기준을 .bru 파일과 수동 README 여러 곳에 흩어두지 않는 것입니다. 가능한 한 OpenAPI 사양을 계약으로 삼고, 문서는 그 결과물로 생성하는 편이 유지보수에 유리합니다.
문서를 최신 상태로 유지하는 방법
공유 URL이 있어도 내용이 오래되면 의미가 없습니다. 문서 운영에서 가장 흔한 실패는 엔드포인트는 바뀌었는데 문서는 그대로인 경우입니다.
사양 기반 워크플로에서는 다음 원칙을 적용할 수 있습니다.
- API 변경 시 OpenAPI 사양도 함께 변경
- 사양 변경은 PR에서 리뷰
- 문서는 사양에서 자동 생성
- 문서 수정을 별도 수동 작업으로 두지 않음
예를 들어 응답에 email 필드를 추가한다면 사양도 함께 변경합니다.
responses:
"200":
description: 사용자 정보
content:
application/json:
schema:
type: object
properties:
id:
type: string
name:
type: string
email:
type: string
format: email
이렇게 하면 문서도 변경된 응답 스키마를 기준으로 표시됩니다. 엔드포인트 폐기, 요청 파라미터 추가, 인증 방식 변경도 같은 방식으로 관리할 수 있습니다.
권장 워크플로
Bruno를 계속 사용하면서 공개 문서도 필요하다면 다음 구조가 실용적입니다.
개발자 내부 요청 실행
→ Bruno
API 계약 관리
→ OpenAPI spec
공개/공유 문서
→ Apidog hosted documentation
리뷰 및 변경 추적
→ Git + Pull Request
이렇게 역할을 나누면 Bruno의 Git 친화적인 장점은 유지하면서도, 외부 소비자에게 필요한 문서 URL을 제공할 수 있습니다.
FAQ
Bruno는 공개 API 문서를 생성하고 호스팅할 수 있나요?
Bruno는 읽을 수 있는 .bru 컬렉션 파일과 앱 내 마크다운 문서 보기를 제공합니다. 둘 다 Git에서 관리하고 리뷰할 수 있습니다. 하지만 공유 가능한 URL을 가진 내장 호스팅 문서 포털은 제공하지 않습니다. 공개 문서를 만들려면 보통 OpenAPI 사양으로 변환한 뒤 별도 문서 생성 및 호스팅 과정을 구성해야 합니다.
내 API에서 공유 가능한 문서 URL을 만들려면 어떻게 해야 하나요?
API를 OpenAPI 사양으로 정의한 뒤, 해당 사양에서 호스팅 문서를 생성하는 도구를 사용하면 됩니다. Apidog에서는 사양을 가져오고, 문서 가시성을 설정하고, 필요하면 사용자 지정 도메인을 연결한 뒤 게시할 수 있습니다. 결과적으로 API 소비자에게 전달할 수 있는 안정적인 문서 URL이 생성됩니다.
문서를 게시하려면 Bruno 컬렉션을 포기해야 하나요?
아니요. Bruno 컬렉션을 계속 사용하면서 OpenAPI 사양을 문서의 기준으로 둘 수 있습니다. 기존 Bruno 컬렉션을 OpenAPI로 변환하고, 그 사양을 기반으로 문서를 생성하면 됩니다. 이렇게 하면 Bruno에서 쌓은 요청 관리 방식과 Git 기반 리뷰 흐름을 유지하면서 공유 가능한 문서도 제공할 수 있습니다.
문서가 오래되지 않게 하려면 무엇을 기준으로 관리해야 하나요?
수동 README보다 OpenAPI 사양을 기준으로 관리하는 것이 좋습니다. API 변경 사항이 생기면 사양을 함께 수정하고 PR에서 리뷰합니다. 이후 문서는 사양에서 생성되도록 구성하면, 별도 문서 업데이트 작업을 잊어버릴 가능성을 줄일 수 있습니다.
Top comments (0)