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