대화형 API 문서
GitLab API를 위한 대화형 문서 도구를 소개합니다.
OpenAPI 사양에 대한 정보
OpenAPI 사양 (이전 이름: Swagger)은 RESTful API에 대한 표준화되고 언어에 구애받지 않는 인터페이스를 정의합니다. OpenAPI 정의 파일은 YAML 형식으로 작성되며, GitLab 브라우저에 의해 더 읽기 쉬운 인터페이스로 자동 렌더링됩니다.
GitLab API에 대한 일반 정보는 API 문서를 참조하세요.
개요
대화형 API 문서 도구는 GitLab.com 웹사이트에서 API 테스트를 직접 수행할 수 있도록 합니다. OpenAPI 사양으로 문서화된 엔드포인트는 제한적이지만, 현재 목록은 도구의 기능을 보여줍니다.
엔드포인트 매개변수
엔드포인트 목록을 확장하면 설명, 필요 시 입력 매개변수 및 서버 응답 예제를 볼 수 있습니다. 일부 매개변수에는 기본값이나 허용된 값 목록이 포함됩니다.
대화형 세션 시작하기
개인 액세스 토큰 (PAT)은 대화형 세션을 시작하는 한 가지 방법입니다. 이를 위해 메인 페이지에서 Authorize를 선택하면 대화 상자가 나타나고 현재 웹 세션에 유효한 PAT를 입력하라는 메시지가 표시됩니다.
엔드포인트를 테스트하려면 엔드포인트 정의 페이지에서 먼저 Try it out을 선택하세요. 필요한 매개변수를 입력한 후 Execute를 선택합니다. 다음 예에서는 version 엔드포인트에 대한 요청을 실행했습니다(매개변수 필요 없음). 도구는 요청의 curl 명령 및 URL을 보여주고, 그 뒤에 반환된 서버 응답이 표시됩니다. 관련 매개변수를 편집하여 새로운 응답을 생성한 후 다시 Execute를 선택할 수 있습니다.
비전
API 코드는 단일 진실의 출처이며, API 문서는 그 구현에 밀접하게 연결되어야 합니다. OpenAPI 사양은 API를 문서화하는 표준화되고 포괄적인 방법을 제공합니다. 이는 GitLab REST API를 문서화하는 주요 형식이 되어야 합니다. 이는 더 정확하고 신뢰할 수 있으며 사용자 친화적인 문서를 만들어 GitLab REST API 사용의 전반적인 경험을 향상시킵니다.
이를 달성하기 위해서는 API 코드 변경이 있을 때마다 OpenAPI 사양을 업데이트하는 것이 요구되어야 합니다. 이를 통해 문서가 항상 최신이며 정확하도록 보장하여 사용자에게 혼란과 오류의 위험을 줄일 수 있습니다.
OpenAPI 문서는 API 코드에서 자동 생성되어야 하며, 이를 통해 최신 상태를 유지하고 정확성을 쉽게 확보할 수 있도록 합니다. 이는 우리 문서 팀의 시간과 노력을 절약하게 됩니다.
이 비전의 현재 진행 상황은 OpenAPI V2로 REST API 문서화 에픽에서 확인할 수 있습니다.
도움말