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 탐색기 설정

  • 누구나 그래픽 탐색기의 왼쪽 창에 포함시킬 수 있는 쿼리가 든 코드 블록 포함: 

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

  • 사용자에게 할 일 알려주기: 

    1. 다음 URL에서 GraphiQL 탐색 도구를 엽니다: `https://gitlab.com/-/graphql-explorer`.
1. 위에 나열된 `query`를 그래픽 탐색 도구의 왼쪽 창에 붙여넣기합니다.
1. 결과가 여기에 표시되도록 **실행**을 선택합니다:
  • GraphiQL 탐색기에서 결과의 스크린샷 포함. Documentation style guide의 이미지 저장 섹션에서 설명된 네이밍 컨벤션을 따르십시오.
  • 결과를 사용하여 수행할 수 있는 예제를 추가로 제공하십시오. 독자가 자체 배포에서 수행할 수 있는 예제여야 합니다.
  • GraphQL API 리소스에 대한 링크 추가.

전역 탐색에 GraphQL 예제 추가

새 문서에 대한 링크를 전역 탐색(문서 웹사이트 왼쪽에 있는 디렉터리)에 포함해야 합니다. 이를 위해 GitLab Documentation repository에 대한 두 번째 MR을 엽니다.

전역 탐색은 content/_data 하위 디렉터리의 navigation.yaml 파일에 저장됩니다. GraphQL 섹션은 다음 라인 아래에 있습니다. 

- category_title: GraphQL

두 번째 MR의 CI 테스트가 메인 MR이 Merge될 때까지 잘못된 링크로 실패하기 때문에 주의하십시오. 따라서 콘텐츠가 Merge되어 docs.gitlab.com에 라이브 상태가 된 후에만 gitlab-docs 리포지터리에 대한 MR을 Merge해야 합니다.