API 문서 생성기은(는) 무엇을 하나요?
이 스킬은 코드베이스의 API 라우트 파일로부터 OpenAPI 3.0 (Swagger) 문서를 자동 생성합니다.
이 스킬을 사용해야 할 때
- 사용자가 API 문서 생성을 요청할 때
- REST API 엔드포인트 작업 시
- OpenAPI/Swagger 명세를 생성하거나 업데이트해야 할 때
- Express, FastAPI, Flask, NestJS 또는 유사한 프레임워크의 API 문서를 설정할 때
지침
1. API 라우트 발견
코드베이스에서 API 라우트 정의를 검색하세요:
- Express/Node.js:
app.get(),app.post(),router.get()등을 찾습니다. - FastAPI/Python:
@app.get(),@router.post()데코레이터를 찾습니다. - Flask:
@app.route()데코레이터를 찾습니다. - NestJS:
@Get(),@Post(),@Controller()데코레이터를 찾습니다. - Rails:
config/routes.rb파일에서 라우트를 찾습니다.
Glob을 사용하여 라우트 파일을 찾으세요 (예: **/*routes*.{js,ts,py}, **/controllers/**/*.{js,ts}).
2. 라우트 패턴 분석
발견된 각 라우트에 대해 다음을 추출하세요:
- HTTP 메서드: GET, POST, PUT, PATCH, DELETE
- 경로: 엔드포인트 URL (예:
/api/users/:id) - 파라미터: 경로 파라미터, 쿼리 파라미터, 요청 본문
- 응답: 예상 응답 구조
- 인증: 인증 필요 여부
- 설명: 라우트 근처의 주석 또는 docstring
3. OpenAPI 명세 생성
OpenAPI 3.0 명세 파일(일반적으로 openapi.yaml 또는 swagger.json)을 생성하거나 업데이트하세요:
templates/openapi-3.0.yaml템플릿으로 시작- 각 라우트를 OpenAPI path 객체에 매핑
- JSON Schema를 사용하여 요청/응답 스키마 정의
- 파라미터 정의 포함 (경로, 쿼리, 본문)
- 감지된 인증 체계 추가 (Bearer, API Key, OAuth2)
- 태그별로 엔드포인트 그룹화 (예: "Users", "Products", "Auth")
4. 완전성 검증
생성된 문서에 다음이 포함되어 있는지 확인하세요:
- 발견된 모든 엔드포인트
- 정확한 HTTP 메서드와 경로
- 가능한 경우 요청/응답 예제
- 오류 응답 (400, 401, 404, 500 등)
- 보안 요구사항
5. 출력 위치
- 프로젝트 루트에
openapi.yaml로 저장하거나 docs/또는api/디렉토리가 존재하면 해당 위치에 저장- 위치가 명확하지 않은 경우 사용자에게 선호하는 위치를 물어보세요.
프레임워크별 참고 사항
Express/Node.js
- 인증/유효성 검사에 영향을 줄 수 있는 라우트 미들웨어 확인
- 요청 유효성 검사기(Joi, express-validator 등) 찾기
- 엔드포인트 설명을 위한 JSDoc 주석 추출
FastAPI
- FastAPI는 OpenAPI 문서를 자동 생성하지만, 이 스킬로 더 향상시킬 수 있습니다.
- 요청/응답 스키마를 위한 Pydantic 모델 추출
response_model및status_code파라미터 확인
NestJS
- 스키마를 위한 DTO (데이터 전송 객체) 찾기
- Swagger 데코레이터 (
@ApiOperation,@ApiResponse) 확인 - 컨트롤러 및 메서드 데코레이터에서 메타데이터 추출
모범 사례
- 기존 스키마 사용: 코드베이스에 TypeScript 인터페이스, Pydantic 모델 등이 있으면 정확한 스키마를 위해 사용하세요.
- 예제 포함: 사용 가능한 경우 테스트에서 요청/응답 예제를 추가하세요.
- 논리적으로 그룹화: 태그를 사용하여 리소스 또는 기능 영역별로 엔드포인트를 구성하세요.
- 적절한 버전 지정: 코드베이스의 API 버전을 사용하세요 (예: "1.0.0").
- 설명 추가: 엔드포인트 설명에 코드 주석/docstring을 사용하세요.
지원 파일
templates/openapi-3.0.yaml: 기본 OpenAPI 템플릿examples.md: 프레임워크별 예제