api-documentation-generator은(는) 무엇을 하나요?
코드에서 엔드포인트, 파라미터, 예제, 모범 사례를 포함한 포괄적이고 개발자 친화적인 API 문서를 생성합니다.
개요
이 스킬은 소스 코드를 분석하여 API 문서를 자동 생성합니다. 개발자는 더 이상 문서 작성을 위해 시간을 낭비할 필요 없이, 일관되고 정확한 문서를 빠르게 얻을 수 있습니다.
주요 기능
- 엔드포인트 추출: 코드에서 정의된 모든 API 엔드포인트를 자동으로 감지합니다.
- 파라미터 문서화: 각 엔드포인트의 요청 및 응답 파라미터, 헤더, 쿼리 문자열 등을 상세히 설명합니다.
- 예제 생성: 실제 사용 예제를 자동으로 생성하여 API 사용법을 명확히 합니다.
- 모범 사례 통합: RESTful 원칙, 인증, 오류 처리, 속도 제한 등 API 설계 모범 사례를 문서에 포함합니다.
- 형식 지원: OpenAPI/Swagger, Markdown, HTML 등 다양한 출력 형식을 지원합니다.
사용 방법
- 프로젝트의 소스 코드가 있는 디렉토리에서 스킬을 호출합니다.
- 스킬이 코드베이스를 분석하여 엔드포인트와 관련 정보를 추출합니다.
- 생성된 문서는 기본적으로
docs/api/디렉토리에 저장되며, 필요에 따라 출력 경로를 지정할 수 있습니다.
예제 명령어
# markdown 파일로 문서 생성
npm run api-docs -- --format markdown
# OpenAPI 명세 생성
npm run api-docs -- --format openapi --output ./output
구성 옵션
| 옵션 | 설명 | 기본값 |
|---|---|---|
--format | 출력 형식 (markdown, openapi, html) | markdown |
--output | 출력 디렉토리 경로 | ./docs/api |
--include | 포함할 파일 패턴 (glob) | **/*.{js,ts,py} |
--exclude | 제외할 파일 패턴 | node_modules |
--title | 문서 제목 | API Documentation |
지원 언어
- JavaScript / TypeScript (Express, Fastify, NestJS 등)
- Python (Flask, Django, FastAPI 등)
- Java (Spring Boot 등)
- Go (Gin, Echo 등)
- Rust (Actix, Rocket 등)
모범 사례
- JSDoc/주석 활용: 코드에 JSDoc, Sphinx, 또는 기타 문서 주석을 추가하면 더 풍부한 문서를 생성할 수 있습니다.
- 일관된 명명 규칙: 엔드포인트와 파라미터에 일관된 명명 규칙을 사용하면 더 정확한 문서가 생성됩니다.
- 정기적인 업데이트: 코드 변경 시 문서를 재생성하여 항상 최신 상태를 유지하세요.
- 보안 정보 포함 금지: 문서에 비밀 키, 토큰, 비밀번호 등 민감한 정보를 포함하지 마세요.
문제 해결
문서 생성이 예상대로 되지 않는 경우:
- 코드에 충분한 주석과 타입 정보가 있는지 확인하세요.
- 지원되는 프레임워크 또는 라이브러리를 사용 중인지 확인하세요.
- 파일 패턴 옵션(
--include,--exclude)을 조정하여 분석할 파일을 제한하세요. - 더 자세한 로그를 보려면 디버그 모드를 활성화하세요.
라이선스
이 스킬은 MIT 라이선스에 따라 제공됩니다.