GraphQL 예제 페이지 만들기

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

그러나 다양한 사용 사례에 대한 GraphQL 사용 방법을 예제로 포함하면 도움이 됩니다. 독자가 GraphiQL 탐색기에서 직접 사용할 수 있는 샘플을 포함해야 합니다.

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

전용 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. **Play**를 선택하여 여기에서 보여주는 결과를 가져옵니다:
  • GraphiQL 탐색기에서 결과 스크린샷을 포함하세요. 이미지 요구사항에서 설명한 명명 규칙을 따르세요.
  • 출력으로 할 수 있는 작업의 예시를 포함하세요. 이 예시가 독자가 자신의 배포에서 할 수 있는 것인지 확인하세요.
  • GraphQL API 리소스로의 링크를 포함하세요.

전역 탐색기에 GraphQL 예제 추가

새 문서에 대한 링크를 전역 탐색기(문서 웹사이트 왼쪽의 목록)에 포함해야 합니다. 이를 위해 GitLab 문서 저장소에 대한 두 번째 MR을 엽니다.

우리는 전역 탐색기를 navigation.yaml 파일에 저장합니다. content/_data 하위 디렉토리에 있습니다. 다음 줄 아래에서 GraphQL 섹션을 찾을 수 있습니다:

- category_title: GraphQL

두 번째 MR에 대한 CI 테스트가 나쁜 링크로 실패할 것이라는 점을 유의하세요. 새로운 GraphQL 페이지를 추가하는 주요 MR이 병합될 때까지입니다. 따라서 새로운 GraphQL 페이지의 콘텐츠가 병합되고 docs.gitlab.com에서 실시간으로 활성화된 후에만 gitlab-docs 저장소에 대한 MR을 병합하세요.