대화형 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을 선택하여 엔드포인트를 테스트합니다. 필요한 매개변수를 입력한 후 실행을 선택합니다. 다음 예에서는 version 엔드포인트에 대한 요청을 실행했습니다(매개변수가 필요하지 않음). 도구는 요청의 curl 명령과 URL을 보여주며, 서버 응답을 반환합니다. 해당 매개변수를 편집하여 새로운 응답을 생성한 다음, 다시 실행을 선택할 수 있습니다.
비전
API 코드는 단일한 진리의 근원이며, API 문서는 해당 구현과 밀접하게 결합되어야 합니다. OpenAPI 명세는 API를 문서화하는 표준화된 및 포괄적인 방법을 제공합니다. GitLab REST API를 문서화하기 위한 지침 형식으로 사용해야 합니다. 이로써 GitLab REST API를 사용하는 전반적인 경험을 향상시키는 보다 정확하고 신뢰할 수 있으며 사용자 친화적인 문서가 작성됩니다.
이를 실현하기 위해 모든 API 코드 변경 사항에 대해 OpenAPI 명세를 업데이트해야 하는 요구사항이 되어야 합니다. 이렇게 함으로써 문서가 항상 최신이며 정확하게 유지되어 사용자들에게 혼란과 오류의 위험을 줄이게 됩니다.
OpenAPI 문서는 API 코드에서 자동으로 생성되어야 하므로 항상 최신이고 정확하게 유지하는 것이 쉬워져야 합니다. 이를 통해 문서 팀의 시간과 노력을 절약할 수 있습니다.
현재 이러한 비전의 진행 상황은 OpenAPI V2 엡릭스에서 REST API 문서화에서 확인할 수 있습니다.
도움말