GraphQL 예제 페이지 만들기

GraphQL API는 RESTful API와 다릅니다. 참고 정보는 GraphQL API 리소스 페이지에서 생성됩니다.

그러나 다양한 사용 사례에 대한 GraphQL 사용 예제를 포함하는 것이 도움이 됩니다. 독자가 GraphiQL 탐색기에서 직접 사용할 수 있는 샘플과 함께 설명하는 것이 좋습니다.

이 섹션에서는 GitLab 문서에 GraphQL 예제를 추가하는 데 필요한 단계를 설명합니다.

전용 GraphQL 페이지 추가

전용 GraphQL 페이지를 만들려면 doc/api/graphql/ 디렉토리에 새로운 .md 파일을 만듭니다. import_from_specific_location.md와 같이 기능적인 이름을 지정합니다.

설명으로 페이지 시작

다음과 같이 몇 마디로 GraphQL 기능을 설명하는 페이지 제목을 포함합니다. 

# [종류별 데이터] 검색

검색에 대해 설명합니다. 한 문장이면 충분할 수 있습니다. 더 많은 정보는 독자가 자신들의 GitLab 배포에 예제를 사용하는 방법을 배울 수 있도록 도와줄 수 있습니다.

GraphiQL 탐색기를 사용한 절차 포함

GraphiQL 탐색기를 사용하면 작동 중인 배포에서 쿼리를 테스트할 수 있습니다. 다음과 같이 섹션을 설정합니다.

  • 다음과 같은 제목을 사용합니다. 

    ## GraphiQL 탐색기 설정

  • 누구나 자신의 GraphiQL 탐색기에 포함할 수 있는 쿼리의 코드 블록을 포함합니다. 

    ```graphql
query {
  <여기에 쿼리 입력>
}
```

  • 사용자에게 해야 할 일을 알려줍니다. 

    1. 다음 URL에서 GraphiQL 탐색 도구를 엽니다: `https://gitlab.com/-/graphql-explorer`.
1. 위에서 나열한 `query`를 자신의 GraphiQL 탐색 도구의 왼쪽 창에 붙여넣습니다.
1. 결과를 얻으려면 **실행**을 선택하여 여기에 표시된 결과를 얻습니다:
  • GraphiQL 탐색 도구의 결과 화면 캡처를 포함합니다. 문서 스타일 가이드의 이미지 저장 섹션에 설명된 명명 규칙을 따릅니다.
  • 결과로 무엇을 할 수 있는지 예제를 계속합니다. 독자가 자신들의 배포에서 수행할 수 있는 것이어야 합니다.
  • GraphQL API 리소스에 대한 링크를 포함합니다.

전역 내비게이션에 GraphQL 예제 추가

새 문서에 대한 링크를 전역 내비게이션(문서 웹 사이트 왼쪽에 있는 목록)에 포함해야 합니다. 이를 위해 GitLab documentation repository에 대한 두 번째 MR을 엽니다.

전역 내비게이션은 content/_data 하위 디렉토리의 navigation.yaml 파일에 저장됩니다. GraphQL 섹션은 다음 라인 아래에서 찾을 수 있습니다. 

- category_title: GraphQL

해당 두 번째 MR은 콘텐츠가 병합되어 docs.gitlab.com에 실시간으로 살아 있을 때까지만 병합되어야 합니다. 따라서 새로운 GraphQL 페이지를 추가하는 본 MR이 병합될 때까지 해당 두 번째 MR에 대한 CI 테스트가 잘못된 링크로 실패할 것입니다. 따라서 gitlab-docs 저장소에 대한 MR을 병합하기 전에 내용이 병합되어 docs.gitlab.com에 실시간으로 존재해야 합니다.