Apidog의 IDEA 플러그인 또는 일부 Swagger 플러그인을 사용하면 코드에서 API 문서를 쉽게 생성하여 문서를 처음부터 작성해야 하는 문제를 해결할 수 있습니다.
하지만 엔드포인트가 작성되고 문서가 생성된 후에도 여전히 의구심이 들 수 있습니다. API 디자인이 충분히 좋은가? 문서가 표준화되어 있는가? 추가로 개선할 수 있는 영역은 없는가?
특히 팀 협업에서는 팀원이 API 문서를 한눈에 이해하기 쉽게 만들고 싶을 것입니다. 이름의 명확성과 정보의 완전성은 API 사용 경험에 직접적인 영향을 미칩니다.
Apidog은 최근 이 단계에서 API 문서를 더욱 최적화하는 데 도움이 되는 여러 AI 기능을 출시했습니다. 기존 엔드포인트 세부 정보를 개선하거나 다른 곳에서 기존 API 문서를 가져오는 경우, AI가 실용적인 제안을 제공할 수 있습니다.
아래에서는 Apidog에서 AI를 사용하여 더욱 표준화된 API 문서를 만드는 방법을 안내해 드릴 것입니다. 시작하기 전에 Apidog을 최신 버전으로 업데이트하고, AI 기능을 활성화했으며, AI 모델을 구성했는지 확인하십시오.
기존 문서에서 가져오기
때로는 다른 소스에서 Apidog으로 API 문서를 마이그레이션해야 할 수 있습니다. 문서가 표준 형식인 경우 Apidog은 여러 가져오기 방법을 기본적으로 지원합니다. IDEA 플러그인을 통해 코드에서 문서를 생성하거나, OpenAPI/Swagger 사양을 가져오거나, Postman과 같은 다른 도구에서 마이그레이션할 수 있습니다.
하지만 어떤 경우에는 문서가 이러한 표준 형식이 아닐 수도 있습니다. 예를 들어, 팀에서 이전에 Markdown으로 엔드포인트를 문서화했거나, Word에서 필드 설명을 정리했거나, 채팅 기록이나 이메일에서 엔드포인트 정의를 찾았을 수도 있습니다. 이러한 비표준 소스에서 각 필드를 수동으로 Apidog에 입력하는 것은 부담스러울 수 있습니다.
이런 상황에서 데이터 입력을 돕기 위해 AI로 스키마 수정 기능을 사용할 수 있습니다. 다음과 같은 Markdown 콘텐츠가 있다고 가정해 봅시다.
| name | desc | type | required |
| ---------- | --------------------------------------------------------------------------- | --------- | -------- |
| usePaging | Whether to enable pagination | boolean | true |
| offset | Starting position (required when pagination is enabled) | int | false |
| pageSize | Number of items per page (required when pagination is enabled) | int | false |
| minPrice | Minimum price (unit: cents) | int | false |
| maxPrice | Maximum price (unit: cents) | int | false |
| brand | Brand code | string | false |
| categoryId | Product category ID | int | false |
| sortRule | Sorting rule: 1 → Sales priority, 2 → Price ascending, 3 → Price descending | enum(int) | false |
| keyword | Search keyword (fuzzy match on product name) | string | false |매개변수를 복사하고 AI에게 요청하기만 하면 됩니다. "이 콘텐츠를 엔드포인트 매개변수로 변환하고, 유형과 필수 필드를 식별해 주세요."
AI는 필드 이름, 데이터 유형, 필수 여부 및 설명을 자동으로 감지한 다음 모든 것을 Apidog의 표준 스키마 형식으로 변환합니다. 열거형이 포함되어 있다면 AI가 적절한 열거형 유형으로 정리해 줄 것입니다.
AI가 API 세부 정보 개선을 돕습니다
기본 정보를 가져온 후 다음 단계는 세부 정보를 다듬는 것입니다.
필드 이름이 확실하지 않다면 AI 이름 지정 기능을 사용해 보세요. AI는 엔드포인트 사양과 API 디자인 가이드라인에 따라 더 정확한 이름 지정 제안을 제공할 것입니다.
AI를 사용하여 필드 설명을 자동 완성하여 더 명확하고 완전한 설명을 만들 수도 있습니다.
모의 데이터 생성은 AI의 또 다른 강점입니다. 종종 필드가 무엇을 나타내는지 알지만 어떤 예시 값을 사용해야 할지 모를 때가 있습니다. AI는 필드 유형과 설명을 기반으로 합리적인 예시 데이터를 자동으로 생성합니다.
API 문서 완전성 검사: 누락 방지
문서가 거의 완성된 것처럼 보일 때도 혹시 중요한 정보가 누락되지 않았는지 궁금할 수 있습니다. 이 시점에서 Apidog의 API 문서 완전성 검사를 사용하여 누락된 것이 있는지 확인할 수 있습니다.
AI는 기존 API 문서를 여러 관점에서 스캔하여 누락되거나 불완전한 정보를 식별합니다. 그런 다음 각 검토 항목에 점수를 매긴 상세 보고서를 생성하여 API 문서가 개선이 필요한 부분을 빠르게 파악할 수 있도록 돕습니다.
이 보고서는 무엇을 해야 할지 알려줄 뿐만 아니라 그 이유도 설명합니다. 예를 들어, 성공적인 응답 형식은 문서화했지만 발생 가능한 오류 시나리오를 빠뜨렸을 수 있습니다. 기본적인 필드 설명은 있지만 사용 제약 조건이나 서식 요구 사항이 부족할 수 있습니다.
보고서에 제공된 제안을 따르면 API 문서를 개선할 수 있습니다.
엔드포인트 준수 검사: 일관성 보장
완전함과 더불어 API 문서는 잘 표준화되어야 합니다. 단일 엔드포인트 내에서 이름은 일관된 스타일을 따라야 하며, 필드 유형은 명확하고 정확하게 정의되어야 하고, 응답 구조는 논리적이어야 합니다. 이러한 세부 사항은 문서를 읽기 쉽고 유지 관리하기 쉽게 만드는 데 중요한 역할을 합니다.
Apidog의 엔드포인트 준수 검사 기능은 여러 각도에서 문서를 검토합니다. 예를 들어, 일부 필드가 동사로 명명되고 다른 필드가 명사를 사용하는 경우, AI는 불일치를 표시하고 통일된 명명 스타일을 권장합니다.
또한 필드 정의가 일관된 표준을 따르는지 확인합니다. 예를 들어, 혼합된 대소문자 스타일, 밑줄과 camelCase의 동시 사용, 일관되지 않은 약어 사용을 피하는지 등을 확인하고, 이러한 문제를 해결하는 방법에 대한 명확한 제안을 제공합니다.
요약
명확하고 표준화된 API 문서를 만드는 것은 필수적입니다. AI 생성 테스트 케이스와 같은 기능은 문서의 품질에 따라 달라집니다. 문서가 완전하고 일관될수록 생성되는 테스트 케이스는 더욱 정확하고 유용할 것입니다.
모든 AI 기능을 한 번에 사용하거나 현재 워크플로우를 전면 개편할 필요는 없습니다.
이것은 점진적인 과정입니다. 기존 문서를 가져오는 것부터 시작하여 AI 기능을 천천히 적용하여 개선하고 다듬을 수 있습니다. 제안에 대해 확신이 없다면, 그대로 두었다가 더 많은 맥락을 파악한 후에 다시 검토할 수 있습니다.
시간이 지남에 따라 API 문서 표준에 대한 이해를 자연스럽게 높일 수 있을 것입니다. AI는 당면한 문제를 해결하는 데 도움을 줄 뿐만 아니라 더 나은 문서 작성 습관을 기르도록 돕습니다.