api-documenter

api-documenter 스킬 개요

api-documenter가 하는 일

api-documenter 스킬은 에이전트가 OpenAPI/Swagger 스펙 형태의 API 문서를 만들고 다듬도록 돕습니다. REST 스타일 API 구조를 중심으로 지원하며, GraphQL은 가볍게만 언급됩니다. 실제로는 빈 파일에서 openapi.yaml을 처음부터 쓰거나, 막연한 “API 문서 작성해줘” 프롬프트로 시작하는 것보다 더 빠르게 실사용 가능한 초안을 만들고 싶을 때 가장 유용합니다.

누가 api-documenter를 써야 하나

엔드포인트, 요청/응답 형태, 인증, 에러 처리를 표준화된 기계 판독형 포맷으로 문서화해야 하는 개발자, 테크니컬 라이터, DX 팀, 플랫폼 엔지니어에게 가장 잘 맞습니다. 특히 팀에서 만든 문서를 나중에 Swagger UI, 코드 생성, 검증, 리뷰 워크플로에 연결하려는 경우 api-documenter skill의 가치가 큽니다.

실제로 해결하는 핵심 과제

대부분의 사용자는 단순히 “문서를 쓰는” 것이 아닙니다. 여기저기 흩어진 API 지식을, 다른 사람이 리뷰하거나 구현에 참고하거나 배포할 수 있을 정도로 타당한 OpenAPI 초안으로 정리하려는 것입니다. api-documenter는 API 동작 자체는 이미 알고 있고, 그걸 구조적이고 빠짐없이 일관되게 정리해야 할 때 가장 강합니다.

왜 일반 프롬프트보다 api-documenter를 선택할까

차별점은 고도화된 자동화가 아니라, 구조를 잡아주는 가이드에 있습니다. 저장소에는 다음이 포함되어 있습니다.

• references/openapi-template.yaml의 명확한 OpenAPI 3.0.3 시작 템플릿
• scripts/generate_openapi.py의 스타터 생성기
• scripts/validate_openapi.py의 간단한 검증기
• 포맷 추측을 줄여주는 예제

즉, 실제 API 세부사항은 여전히 직접 제공해야 하지만, api-documenter usage는 즉흥적인 프롬프트보다 훨씬 반복 가능하고 재현 가능한 방식으로 작업하게 해줍니다.

이 스킬이 대신 해주지 않는 것

이 스킬은 실제 운영 중인 API를 자동으로 발견하지 않으며, 코드만 보고 모든 스키마를 정확히 추론하지도 않고, OpenAPI의 의미론적 정확성까지 완전하게 검증하지도 않습니다. 포함된 검증기는 문자열 기반으로 필수 섹션 존재 여부만 확인합니다. 따라서 이 스킬은 “권위 있는 스키마 추출”보다는 “가이드된 초안 작성 워크플로”가 필요할 때 도입하는 편이 맞습니다.

api-documenter 스킬 사용 방법

api-documenter 설치 맥락

이 스킬은 zhaono1/agent-playbook 저장소의 skills/api-documenter에 있습니다: https://github.com/zhaono1/agent-playbook/tree/main/skills/api-documenter.

사용 중인 skills 환경이 GitHub 직접 설치를 지원한다면, 원격 스킬 컬렉션을 추가하는 해당 도구의 설치 흐름을 따르면 됩니다. 지원하지 않는다면 저장소를 클론한 뒤, 에이전트 도구가 로컬 스킬 디렉터리를 바라보도록 설정하면 됩니다. 일반적으로 많이 쓰는 기본 설치 패턴은 다음과 같습니다.

npx skills add https://github.com/zhaono1/agent-playbook --skill api-documenter

환경마다 방식이 다를 수 있지만, 핵심 요구사항은 에이전트가 skills/api-documenter/SKILL.md와 그 보조 파일들을 읽을 수 있어야 한다는 점입니다.

처음 쓰기 전에 읽어야 할 파일

빠르게 api-documenter guide를 파악하려면 아래 순서로 읽는 것이 좋습니다.

1. 활성화 조건과 기대되는 문서 형태를 확인할 수 있는 SKILL.md
2. 최소 골격을 보여주는 references/openapi-template.yaml
3. 어떤 시작 파일을 생성하는지 볼 수 있는 scripts/generate_openapi.py
4. 내장 검사가 실제로 무엇을 확인하는지 이해하기 위한 scripts/validate_openapi.py
5. 아주 작은 예제를 담은 references/examples/openapi-example.yaml

이 순서가 중요한 이유는, 이 저장소가 장문의 핸드북이라기보다 워크플로 골격으로서 더 유용하기 때문입니다.

이 스킬이 필요로 하는 입력

api-documenter는 다음처럼 구체적인 원천 자료를 줄 때 가장 잘 작동합니다.

• 메서드와 경로가 포함된 엔드포인트 목록
• 요청 파라미터와 바디 필드
• 응답 예시와 상태 코드
• 인증 방식
• base URL 또는 환경 정보
• 객체/스키마 정의
• 네이밍 규칙과 태그

그저 “이 API 문서화해줘”라고만 하면 일반적인 틀 수준의 결과가 나오기 쉽습니다. 반대로 엔드포인트별 사실 정보를 주면, 리뷰 가능한 수준에 훨씬 가까운 초안을 얻을 수 있습니다.

대충 쓴 요청을 강한 프롬프트로 바꾸기

약한 프롬프트:

Create OpenAPI docs for my API.

더 강한 프롬프트:

Use the api-documenter skill to draft an OpenAPI 3.0.3 spec for a REST API.

Base URL: https://api.example.com/v1
Auth: Bearer token in Authorization header

Endpoints:
- GET /users?page={number}&limit={number}
  - 200 returns array of User plus pagination metadata
- POST /users
  - body: name, email
  - 201 returns created User
  - 409 if email already exists
- GET /users/{id}
  - 200 returns User
  - 404 if missing

Schemas:
- User: id string, name string, email string, createdAt string(date-time)

Please include:
- summary, operationId, description, tags
- parameters and requestBody
- success and error responses
- components.schemas
- components.securitySchemes

강한 버전이 더 잘 먹히는 이유는, OpenAPI 필수 섹션을 채울 수 있을 만큼 충분한 구조를 제공하면서도 비즈니스 로직을 임의로 지어내게 만들지 않기 때문입니다.

아무것도 없는 상태라면 먼저 포함된 생성기를 사용하기

아직 스펙이 전혀 없다면, 먼저 골격부터 생성하세요.

python scripts/generate_openapi.py --output openapi.yaml --name users --version 1.0.0 --base-url https://api.example.com

이 방식이 유용한 이유는 info, servers, paths, 샘플 스키마 블록이 포함된 문법적으로 정돈된 시작점을 만들어주기 때문입니다. 그 다음 스킬을 사용해 플레이스홀더를 실제 엔드포인트와 스키마 정보로 교체하면 됩니다.

api-documenter가 만든 결과 검증하기

편집이 끝났다면 포함된 검증기를 실행하세요.

python scripts/validate_openapi.py --input openapi.yaml

이 검증기는 의도적으로 가볍습니다. openapi:, info:, servers:, paths:, components:, securitySchemes: 같은 필수 헤딩이 파일 안에 존재하는지 확인합니다. 초안이 덜 채워진 상태인지는 잘 잡아주지만, 스펙이 완전히 유효하다는 보증 수단은 아닙니다.

테크니컬 라이팅을 위한 추천 워크플로

api-documenter for Technical Writing 관점에서 실무적으로 쓸 만한 흐름은 다음과 같습니다.

1. 엔지니어, 코드, Postman 컬렉션, 기존 문서에서 원천 정보를 수집한다
2. 생성기를 돌리거나 템플릿 골격을 복사한다
3. 설명문 위주가 아니라 엔드포인트 사실 정보 중심으로 스킬에 프롬프트를 준다
4. 네이밍 일관성, 응답 커버리지, 인증 정보를 리뷰한다
5. 검증기를 실행한다
6. 최종 리뷰를 위해 엔지니어에게 넘기거나 Swagger 도구에서 렌더링한다

이 흐름이 테크니컬 라이터에게 잘 맞는 이유는, 구조를 잡는 부담은 줄여주면서도 편집 판단은 사람에게 남겨두기 때문입니다.

이 스킬이 최적화한 것으로 보이는 것

저장소 내용을 보면, 이 스킬은 주로 다음에 맞춰 최적화되어 있습니다.

• OpenAPI 3.0.3 구조
• 빠짐없는 엔드포인트 섹션
• 엔드포인트별 필수 항목과 권장 항목의 명시
• 표준화와 리뷰에 충분한 수준의 문서

반면 고급 멀티파일 스펙, callbacks, webhooks, 다형성, 또는 완전한 GraphQL 스키마 문서화 워크플로에는 상대적으로 덜 최적화되어 있습니다.

출력 품질을 높이는 실전 팁

작아 보여도 아래 선택들이 api-documenter usage 품질을 크게 좌우합니다.

• “에러 처리함”처럼 쓰지 말고 정확한 상태 코드를 제공하기
• 각 엔드포인트마다 최소 하나 이상의 구체적인 응답 형태를 포함하기
• 필드가 required인지, nullable인지, enum인지, 특정 포맷인지 명시하기
• 인증 방식은 한 번 정의하고, 스킬에 일관되게 참조하도록 요청하기
• 팀이 도구 연동을 시작하기 전에 안정적인 operationId 네이밍을 먼저 정하기

이런 정보가 있어야 가장 흔한 실패 패턴, 즉 보기에는 그럴듯하지만 실제 운영 관점에서는 모호한 스펙을 피할 수 있습니다.

api-documenter를 커스터마이즈할 때 먼저 볼 저장소 경로

자체 워크플로에 맞게 스킬을 조정하고 싶다면, 우선 다음 파일부터 보세요.

• skills/api-documenter/SKILL.md
• skills/api-documenter/references/openapi-template.yaml
• skills/api-documenter/scripts/generate_openapi.py
• skills/api-documenter/scripts/validate_openapi.py

이 경로를 따라가면 활성화 규칙, 작성 템플릿, 스타터 생성, 품질 게이트를 한 번에 파악할 수 있습니다.

api-documenter 스킬 FAQ

api-documenter는 초보자에게도 괜찮을까?

네, 다만 자신의 API를 이미 이해하고 있다는 전제에서는 그렇습니다. 이 스킬은 OpenAPI 포맷 작성의 마찰을 줄여주지만, 스펙 전체를 깊이 있게 가르쳐주지는 않습니다. 초보자라도 구체적인 엔드포인트 메모를 갖고 있고, 결과를 템플릿 및 예제 파일과 비교해가며 확인할 수 있다면 충분히 효과적으로 쓸 수 있습니다.

api-documenter는 REST API 전용인가?

실무적으로는 대부분 그렇다고 보는 편이 맞습니다. 설명에는 REST나 GraphQL이 함께 언급되지만, 저장소 근거를 보면 OpenAPI/Swagger 패턴, 샘플 YAML, RESTful 경로 예시, 엔드포인트 중심 문서화에 초점이 맞춰져 있습니다. 주된 업무가 GraphQL 스키마나 resolver 문서화라면 이 스킬은 최적의 선택이 아닐 수 있습니다.

그냥 AI에게 API 문서를 쓰라고 하는 것과 뭐가 다른가?

api-documenter의 장점은 워크플로의 규율에 있습니다. 활성화 신호, 재사용 가능한 템플릿, 생성 스크립트, 검증 스크립트가 함께 제공됩니다. 일반 프롬프트도 동작할 수는 있지만, 이 스킬은 에이전트에 더 분명한 목표 구조를 주고, 빈 화면 앞에서 내용이 산으로 가는 문제를 줄여줍니다.

api-documenter 설치 시 완전한 검증기도 포함되나?

아니요. 내장 스크립트는 완전한 OpenAPI 파서나 린터가 아니라, 단순한 완성도 체크 도구입니다. 엄격한 검증이 중요하다면 첫 초안 작성 이후 전용 OpenAPI 도구와 함께 쓰는 것이 좋습니다.

언제는 api-documenter를 쓰지 않는 게 나을까?

다음 경우라면 api-documenter는 건너뛰는 편이 낫습니다.

• 사람 입력을 거의 받지 않고 소스 코드에서 자동 추출해야 하는 경우
• API가 주로 GraphQL이고 GraphQL 네이티브 문서가 필요한 경우
• 고급 스펙 거버넌스, 번들링, 린팅, 계약 테스트가 기본 제공되어야 하는 경우
• OpenAPI 산출물보다 사람이 읽는 완성형 설명 문서를 원하는 경우

테크니컬 라이터가 코딩을 많이 하지 않아도 api-documenter를 쓸 수 있나?

네. 가장 강한 활용 사례 중 하나가, 엔드포인트 정보를 수집하고 스타터 스크립트를 실행한 뒤 엔지니어 리뷰를 거쳐 YAML을 다듬는 테크니컬 라이터입니다. 포함된 스크립트를 활용하는 데 깊은 Python 지식까지 필요한 것은 아닙니다.

api-documenter 스킬 개선 방법

api-documenter에 엔드포인트 사실 정보를 완전하게 주기

가장 효과가 큰 개선은 입력 원천 정보를 더 좋게 만드는 것입니다. 각 엔드포인트마다 다음을 제공하세요.

• 메서드와 경로
• 목적
• 파라미터와 바디 스키마
• 상태 코드별 응답 스키마
• 인증 방식
• 예외 상황 또는 에러 응답

이 스킬은 좋은 재료를 구조화하는 데는 강하지만, 신뢰할 수 있는 API 동작을 대신 지어낼 수는 없습니다.

스키마 설명의 모호함 줄이기

약한 API 문서가 되는 가장 흔한 이유 중 하나는 필드 의도가 충분히 드러나지 않기 때문입니다. “user object”라고만 쓰지 말고, 예를 들어 다음처럼 적으세요.

• id: string, immutable
• email: string, unique
• createdAt: string, date-time
• status: enum active | suspended

이렇게 해야 api-documenter가 더 재사용 가능하고, 나중에 갈아엎을 가능성이 적은 components를 만들기 쉽습니다.

포맷 정리만이 아니라 커버리지를 요청하기

더 나은 수정 프롬프트의 예시는 다음과 같습니다.

Review this OpenAPI draft with the api-documenter skill and identify missing:
- operationId values
- requestBody schemas
- error responses
- auth declarations
- shared component schemas
Then patch the spec.

이런 유형의 프롬프트는 단순히 “YAML 좀 정리해줘”라고 하는 것보다 완성도를 높이는 데 훨씬 효과적입니다.

주요 실패 패턴을 미리 점검하기

이 스킬의 출력에서 자주 보이는 문제는 다음과 같습니다.

• 플레이스홀더 설명이 그대로 남아 있음
• components.securitySchemes 누락
• 빈약한 에러 응답 커버리지
• summary는 있지만 의미 있는 스키마 정보가 없는 path operation
• 포함된 검증기는 통과했지만 여전히 불완전한 초안

이 실패 패턴을 알고 있으면 리뷰 속도가 훨씬 빨라집니다.

템플릿에 팀의 스타일 규칙을 함께 적용하기

팀에 네이밍과 문서화 규칙이 있다면, 반드시 명시적으로 전달하세요.

• 도메인 기준 태그 이름
• operationId 동사 스타일
• 페이지네이션 형식
• 에러 envelope 형태
• 날짜 및 enum 규칙

기본 api-documenter skill은 구조를 제공할 뿐이고, 실제로 운영 가능한 결과물을 만드는 것은 팀의 로컬 규칙입니다.

첫 초안 이후에는 반복 수정하기

좋은 2차 수정 프롬프트는 보통 1차보다 범위가 더 좁습니다.

Using the api-documenter skill, revise this spec to normalize schema names, move repeated objects into components.schemas, and add 401/403/404 responses where applicable.

이 방식이 처음부터 다시 생성하는 것보다 나은 이유는, 이미 유용한 구조는 살리면서 일관성을 더 촘촘하게 다듬을 수 있기 때문입니다.

반복적으로 쓰게 된다면 스크립트까지 확장하기

api-documenter를 지속적으로 도입할 계획이라면, 가장 효과가 큰 개선은 헬퍼 스크립트를 팀 워크플로에 맞게 커스터마이즈하는 것입니다. 예를 들면:

• generate_openapi.py가 기본적으로 팀의 인증 방식과 에러 envelope를 포함하도록 수정하기
• validate_openapi.py에 --require를 활용해 추가 필수 헤딩이나 토큰 검사를 넣기
• references/openapi-template.yaml 옆에 팀 전용 스타터 스펙을 함께 보관하기

이렇게 하면 범용 스타터를 팀 전용 문서화 가속기로 바꿀 수 있습니다.