Bruno를 사용하고 계시다면, 그 매력을 이미 아실 겁니다. 여러분의 컬렉션은 Git 리포지토리에 일반 .bru 파일로 저장되며, 코드와 함께 버전이 관리되고 클라우드 계정이 필요 없습니다. 이는 데이터를 소유하려는 API 클라이언트에 대한 깔끔하고 오프라인 우선적인 해답입니다.
하지만 조만간 누군가는 Bruno가 잘 답하지 못하는 질문을 하게 됩니다: “문서는 어디에 있나요? 링크를 보내줄 수 있나요?” 이때 팀은 난관에 부딪힙니다. Bruno는 요청을 보내기 위해 만들어졌지, 공유 가능한 문서 포털을 게시하기 위해 만들어진 것이 아닙니다. 이 가이드는 Bruno API 문서 생성에 대해 솔직하게 다루며, Bruno가 제공하는 것, 제공하지 않는 것, 그리고 소비자에게 전달할 실제 URL이 필요할 때 사양(spec)으로부터 문서를 생성하고 호스팅하는 방법을 설명합니다.
팀이 API 문서에서 실제로 필요로 하는 것
어떤 도구를 판단하기 전에, 목표를 정의하는 것이 도움이 됩니다. 사람들이 “API 문서”라고 말할 때, 보통 다음 세 가지가 함께 작동하는 것을 의미합니다.
- 공유 가능한 URL. 프론트엔드 개발자, 파트너 및 QA는 리포지토리를 복제하거나 클라이언트를 설치하지 않고도 문서를 읽을 수 있어야 합니다. Slack의 링크는 그냥 작동해야 합니다.
- 동기화된 문서. 실제 API와 동떨어진 문서는 오히려 없는 것보다 나쁩니다. 사람들을 잘못된 방향으로 확신하게 만들기 때문입니다. 문서는 사양(spec)을 따라야 합니다.
- 대화형 “직접 해보기(try it)” 경험. 엔드포인트 설명을 읽는 것도 좋지만, 인증 및 샘플 페이로드를 채워 문서화된 엔드포인트에 실제 요청을 보내는 것이 문서를 유용한 참조 자료로 만듭니다.
이 세 가지를 모두 충족하면 문서가 단일 정보원이 됩니다. 하나라도 놓치면 사람들은 직접 질문하게 되고, 이는 확장성이 떨어집니다.
Bruno의 문서 이야기
Bruno에게 공정하게 대합시다. 여기에서 몇 가지를 잘 수행하기 때문입니다.
Bruno의 컬렉션은 사람이 읽을 수 있습니다. .bru 형식은 일반 텍스트이므로, 리포지토리를 탐색하는 엔지니어는 요청 파일을 열어 메서드, URL, 헤더 및 본문을 볼 수 있습니다. Bruno는 또한 요청당 docs 블록과 앱 내 마크다운 문서 보기를 지원하므로, 엔드포인트가 무엇을 하는지 설명하는 산문을 첨부할 수 있습니다. 모든 것이 Git에 있으므로, 이러한 메모는 다른 변경 사항과 마찬가지로 풀 리퀘스트에서 검토됩니다. 코드베이스 내에서 작업하는 내부 팀에게는 이것이 합법적인 문서 형태입니다.
솔직히 부족한 부분은 게시입니다. Bruno는 내장된, 호스팅되고 자동으로 생성되는 공개 문서 포털을 가지고 있지 않습니다. 안정적인 URL과 사용자 지정 도메인을 사용하여 컬렉션을 웹사이트로 변환하는 "게시" 버튼이 없습니다. 인앱 문서 보기는 Bruno가 이미 설치되어 있고 컬렉션을 복제한 사람들에게만 보이며, 이들은 문서가 가장 덜 필요한 대상입니다.
그래서 팀들은 임시방편을 마련합니다. 일반적인 해결책으로는 컬렉션 또는 OpenAPI 파일을 내보내 별도의 정적 문서 생성기에 넣거나, CI에서 문서 사이트를 연결하거나, 누군가가 기억에 의존하여 업데이트하는 수동 작성 README를 유지하는 것이 있습니다. 이러한 방법은 작동할 수 있지만, 유지 관리해야 할 빌드 파이프라인과 정보가 변경될 수 있는 두 번째 장소를 추가합니다. 문서는 더 이상 테스트에 사용하는 도구의 일등 산출물이 아니라 부수적인 프로젝트가 됩니다.
코드로서의 문서(docs-as-code) 원칙
이것에 대해 생각하는 더 깔끔한 방법은, Bruno 사용자들도 이미 절반은 믿고 있는 것인데, 문서를 별개의 산출물이 아닌 사양(specification)의 결과물로 취급하는 것입니다.
코드로서의 문서 워크플로(docs-as-code workflow)에서, API는 일반적으로 OpenAPI와 같은 기계가 읽을 수 있는 사양(spec)으로 한 번 기술됩니다. 이 사양은 Git에 저장되고, 풀 리퀘스트에서 검토되며, 계약 역할을 합니다. 문서, 목 서버 및 클라이언트 SDK는 모두 이 사양으로부터 생성됩니다. 계약이 변경되면, 변경 사항은 한 곳에서 검토되고, 그에 따라 모든 다운스트림이 따릅니다.
장점은 잊어버릴 수 있는 별도의 "문서 업데이트" 작업이 없다는 것입니다. 문서는 사양의 렌더링 결과물입니다. 사양이 올바르고 검토되었다면, 문서도 올바른 것입니다. 이는 Bruno가 컬렉션을 Git에 보관함으로써 암시하는 원칙이지만, 게시 단계까지는 미치지 못합니다.
대신 사양(spec)으로부터 문서를 생성하고 호스팅하세요
이것이 Apidog가 메우기 위해 만들어진 간극입니다. Apidog는 동일한 사양 중심적이고 Git 친화적인 사고방식을 유지하면서, Bruno가 빠뜨린 부분을 추가합니다: 별도의 빌드 파이프라인 없이 사양(spec)으로부터 직접 대화형 호스팅 문서 사이트를 생성합니다.
Apidog에 OpenAPI 사양(spec)을 지정하면 자동으로 문서 포털이 생성됩니다. 그 결과는 다음과 같습니다:
- 공유 가능한 URL로 호스팅되므로, 링크만 있으면 누구든지 아무것도 설치하지 않고 문서를 읽을 수 있습니다.
- 사용자 지정 도메인에 연결할 수 있어,
docs.yourcompany.com과 같은 주소에 문서가 게시되어 브랜드와 일치할 수 있습니다. - 문서화된 매개변수, 헤더 및 인증을 사용하여 실제 요청을 보내는 내장 "직접 해보기(try it)" 패널을 통해 대화형으로 작동합니다.
- 사양(spec)으로부터 생성되므로, 문서는 변경될 수 있는 수동 작성 복사본이 아닌 API가 실제로 선언하는 바를 반영합니다.
동일한 사양(spec)이 Apidog의 테스트 및 목(mocking) 기능도 구동하기 때문에, 하나의 API에 대한 세 가지 설명을 유지할 필요가 없습니다. 한 번 기술하고 재사용하면 됩니다.
안내: 사양(spec)에서 공유 가능한 URL로
OpenAPI 사양(spec)에서 문서를 게시하는 간략한 단계입니다.
| 단계 | 작업 | 결과 |
|---|---|---|
| 1 | Apidog에 OpenAPI 사양(spec)을 가져오거나 작성합니다. | 엔드포인트, 스키마 및 예시가 자동으로 채워집니다. |
| 2 | 프로젝트의 문서 설정(documentation settings)을 엽니다. | 사양(spec)으로부터 문서가 생성되며, 구성할 준비가 됩니다. |
| 3 | 가시성 및 (선택적으로) 사용자 지정 도메인을 선택합니다. | 문서가 공개, 비공개 또는 비밀번호로 보호됩니다. |
| 4 | 게시합니다. | 안정적인 URL에 라이브 호스팅 문서 사이트가 생성됩니다. |
| 5 | 링크를 공유합니다. | 소비자가 문서를 읽고 “직접 해보기(try it)” 요청을 실행합니다. |
이미 Bruno 컬렉션이 있다면, 먼저 OpenAPI로 변환한 다음 해당 사양(spec)을 가져올 수 있습니다. 그 다음 게시 단계는 동일합니다. 핵심은 문서 생성 및 호스팅이 직접 조립해야 하는 파이프라인이 아니라, (이미 갖춰진) 기능이라는 점입니다.
사양(spec) 변경에 따라 문서를 동기화 상태로 유지하기
문서 URL은 정확성이 유지될 때만 유용합니다. 임시방편으로 마련된 설정의 실패 모드는 누군가 엔드포인트 변경 사항을 배포하고 문서를 잊어버리는 것입니다.
문서가 사양(spec)으로부터 생성될 때, 이러한 위험은 줄어듭니다. 사양을 편집하면, 사양 변경은 다른 코드 변경과 마찬가지로 검토를 거치고, 게시된 문서는 새로운 상태를 반영합니다. 기억해야 할 병렬 문서가 없습니다. 응답 스키마에 필드를 추가하면 문서에 나타나고, 엔드포인트를 폐기하면 문서에 그렇게 표시됩니다. 계약을 올바르게 유지하기 위해 이미 수행하는 작업이 문서를 올바르게 유지하는 동일한 작업입니다.
이것이 코드로서의 문서 원칙의 실제적인 이점입니다: 정확성은 규율에 의존하는 별도의 잡일이 아니라, 어차피 원했을 워크플로의 부수적인 결과가 됩니다.
자주 묻는 질문(FAQ)
Bruno는 공개 API 문서를 생성하고 호스팅할 수 있나요?
Bruno는 읽을 수 있는 .bru 컬렉션 파일과 인앱 마크다운 문서 보기를 제공하며, 둘 다 Git에서 검토됩니다. 공유 가능한 URL을 가진 내장된, 호스팅되고 자동으로 생성되는 공개 문서 포털은 포함하지 않습니다. Bruno에서 공개 문서를 게시하려면, 팀은 일반적으로 사양(spec)을 내보내고 별도의 정적 문서 생성기를 실행하며, 이는 유지 관리해야 할 파이프라인을 추가합니다.
내 API에서 공유 가능한 문서 URL을 어떻게 얻을 수 있나요?
OpenAPI 사양(spec)으로 API를 기술한 다음, 그 사양으로부터 호스팅된 문서를 생성하는 도구를 사용하세요. Apidog에서는 사양을 가져오고, 가시성을 구성하며, 선택적으로 사용자 지정 도메인을 연결하고, 게시합니다. 결과물은 안정적인 URL에 있는 라이브 문서 사이트이며, 대화형 “직접 해보기(try it)” 패널이 포함되어 있어 직접 공유할 수 있습니다.
문서를 게시하기 위해 Bruno 컬렉션을 포기해야 하나요?
아니요. 기존 Bruno 컬렉션을 OpenAPI로 변환한 다음, 해당 사양(spec)을 문서 도구로 가져올 수 있습니다. 엔드포인트, 스키마 및 예시가 그대로 유지되며, 사양은 버전 관리를 받습니다. 마이그레이션은 사양 계층에서 이루어지므로, Bruno를 통해 구축한 코드로서의 문서 습관이 여전히 적용됩니다.