대화형 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의 문서화에 대한 기본 형식이어야 합니다. 이를 통해 더 정확하고 신뢰할 수 있으며 사용자 친화적인 문서가 개선될 것입니다.
이를 달성하기 위해 OpenAPI 명세는 모든 API 코드 변경에 대해 업데이트되어야 합니다. 이를 통해 문서가 항상 최신이며 정확하게 유지되므로 사용자에게 혼란과 오류의 위험이 줄어듭니다.
OpenAPI 문서는 API 코드에서 자동으로 생성되어야 하므로 항상 최신이고 정확하게 유지하기 쉽습니다. 이는 우리 문서 팀에 시간과 노력을 절약할 수 있게 될 것입니다.
현재 이 비전의 진행 상황은 OpenAPI V2 에픽에서 REST API 문서화에서 확인할 수 있습니다.
도움말