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 탐색기의 결과를 스크린샷으로 포함하세요. Documentation 스타일 가이드의 이미지 저장 섹션에 설명된 네이밍 컨벤션을 따르세요.
  • 결과로 할 수 있는 예제를 설명하세요. 독자가 자신의 배포에서 할 수 있는 예제여야 합니다.
  • GraphQL API 리소스에 대한 링크를 포함하세요.

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

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

전역 내비게이션은 content/_data 하위 디렉터리의 navigation.yaml 파일에 저장됩니다. GraphQL 섹션이 다음 라인 아래에 위치합니다. 

- category_title: GraphQL

두 번째 MR의 CI 테스트는 새로운 GraphQL 페이지를 추가하는 본 MR이 Merge될 때까지 잘못된 링크로 실패할 것입니다. 따라서 콘텐츠가 docs.gitlab.com에 Merge되어 실제로 사용 가능한 상태일 때에만 gitlab-docs 리포지터리에 대한 MR을 Merge해야 합니다.