OpenAPI 사양 (이전 명칭: Swagger)은 RESTful API에 대한 표준적이고 언어에 독립적인 인터페이스를 정의합니다. OpenAPI 정의 파일은 YAML 형식으로 작성되며, GitLab 브라우저에서 자동으로 더 사람이 읽기 쉬운 인터페이스로 렌더링됩니다.

GitLab API에 대한 일반적인 정보는 GitLab으로 확장하기를 참조하세요.

인터랙티브 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 코드에서 자동 생성되어야 합니다. 이렇게 하면 문서 팀의 시간과 노력을 절약할 수 있습니다.

이 비전의 현재 진행 상황은 Document the REST API in OpenAPI V2 에픽에서 확인할 수 있습니다.