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에 대한 CI 테스트는 메인 MR이 새로운 GraphQL 페이지를 병합할 때까지 잘못된 링크로 실패합니다. 따라서 내용이 병합되어 docs.gitlab.com에 라이브로 배포된 후에만 gitlab-docs 저장소에 대한 MR을 병합하세요.