SmartDocs 업데이트

API 사용자에게 포털 URL을 제공하기 전에 SmartDocs API 참조 문서가 올바르고 API가 문서에 작성된 대로 동작하는지 확인하세요. 생성된 참조 문서와 테스트를 검토하다 보면 변경하고 싶은 내용이 보일 수 있습니다.

이 페이지에서는 다음 주제에 대해 설명합니다.

  • SmartDocs API 참조 문서
  • SmartDocs가 OpenAPI 문서의 필드를 사용하여 SmartDocs를 생성하는 방법
  • SmartDocs를 다시 생성하는 방법
각 작업에 대해 작업 완료에 필요한 최소한의 ID 및 액세스 관리 역할이 제공됩니다. IAM 권한에 대한 자세한 내용은 다음을 참조하세요.

기본 요건

이 페이지에서는 이미 포털을 만들었다고 가정합니다.

SmartDocs API 참조 문서 정보

Endpoints 서비스에 OpenAPI 문서를 배포할 때마다 SmartDocs가 포털에 대한 API 참조 문서를 생성합니다. SmartDocs UI는 최첨단 UI 구성요소 라이브러리인 Angular Material을 기반으로 합니다. 개발자는 SmartDocs API 참조 문서를 검토하고 API 사용해 보기 패널을 사용하여 API 문서에서 나가지 않고도 API와 상호작용할 수 있습니다.

SmartDocs 생성에 사용되는 필드 정보

OpenAPI 문서에는 다음과 비슷한 내용이 포함됩니다.

swagger: "2.0"
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"
host: "echo-api.endpoints.example-project-12345.cloud.goog"

이 필드의 값은 포털에서 다음과 같이 표시됩니다.

  • title: title의 값은 포털 홈페이지에서 프로젝트의 API가 나열된 섹션, API 홈페이지(documentation이라는 단어가 붙음), API 제목 표시줄에 표시됩니다.

  • description: description 값은 API 홈페이지의 제목 아래에 작은 글꼴로 표시됩니다.

  • host: Endpoints 서비스의 이름이기도 한 host 값은 포털 홈페이지에서 프로젝트의 API가 나열된 섹션 및 설정 페이지에서 API 탭에 표시되는 드롭다운 목록에 표시됩니다.

  • version: 주 버전 번호는 API 포털의 URL에 사용됩니다.

Endpoints 포털은 OpenAPI 문서의 paths 섹션에 나열된 각 개별 엔드포인트의 참조 문서를 생성합니다. 다음 발췌문은 Endpoints 포털 데모의 Endpoints 예시 API에서 echo 엔드포인트의 참조 문서를 생성하는 데 사용되는 OpenAPI 문서에서 가져온 것입니다.

paths:
  "/echo":
    post:
      description: "Echo back a given message."
      operationId: "echo"
      produces:
      - "application/json"
      responses:
        200:
          description: "Echo"
          schema:
            $ref: "#/definitions/echoMessage"
      parameters:
      - description: "Message to echo"
        in: body
        name: message
        required: true
        schema:
          $ref: "#/definitions/echoMessage"
      security:
      - api_key: []

echo 엔드포인트의 매개변수는 다음 섹션에서 정의됩니다. 

definitions:
  echoMessage:
    type: "object"
    properties:
      message:
        type: "string"

Endpoints 포털 데모에 사용된 전체 openapi.yaml 파일은 getting-started Endpoints 샘플에 있습니다.

항상 OpenAPI 문서의 속성 정의와 다른 모든 섹션에 description 필드를 포함하는 것이 좋습니다. description 필드는 여러 줄을 포함할 수 있으며 GitHub 맞춤형 마크다운을 지원합니다. 예를 들어 다음은 포털의 API 홈페이지에 글머리 기호 목록을 만듭니다.

swagger: "2.0"
info:
  description: "A simple API to help you learn about Cloud Endpoints.

  * item 1

  * item 2"
title: "Endpoints Example"
  version: "1.0.0"
host: "echo-api.endpoints.example-project-12345.cloud.goog"

SmartDocs 다시 생성

참조 문서를 다시 생성하려면 다음 안내를 따르세요.

  1. OpenAPI 문서를 변경합니다.

  2. OpenAPI 문서(다음 명령어에서 openapi.yaml)를 다시 배포합니다.

    gcloud endpoints services deploy openapi.yaml

  3. 포털 페이지를 새로고칩니다.

명령어에 대한 자세한 내용은 gcloud endpoints services deploy를 참조하세요.