SmartDocs 업데이트

2022년 3월 21일부터 Cloud Endpoints 포털이 지원 중단됩니다. 2023년 3월 21일 이후에는 Cloud Endpoints 포털을 더 이상 사용할 수 없습니다. Cloud Endpoints에서 관리하는 API 트래픽은 이 변경의 영향을 받지 않습니다. 자세한 내용은 기능 지원 중단을 참조하세요.

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

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

• SmartDocs API 참조 문서
• SmartDocs에서 SmartDocs를 생성하기 위해 Cloud Endpoints Frameworks에서 만든 openapi.json 파일의 필드를 사용하는 방법
• SmartDocs를 다시 생성하는 방법 각 작업에서 작업을 완료하기 위해 필요한 최소한의 ID 및 액세스 관리 역할이 제공됩니다. IAM 권한에 대한 자세한 내용은 다음을 참조하세요.
  • 역할 이해
  • 리소스에 대한 액세스 권한 부여, 변경, 취소
  • 커스텀 역할 생성 및 관리

기본 요건

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

SmartDocs API 참조 문서 정보

다음 항목에 설명된 대로 API 관리를 추가할 수 있습니다.

• 자바: API 관리 추가
• Python: API 관리 추가

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

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

다음 항목에 설명된 대로 API 관리를 추가할 수 있습니다.

• 자바: API 관리 추가
• Python: API 관리 추가

Endpoints Frameworks는 API의 JSON 형식으로 OpenAPI 문서를 만듭니다. OpenAPI 문서를 배포할 때(gcloud endpoints services deploy 사용) SmartDocs는 Endpoints Frameworks가 만든 OpenAPI 문서를 기반으로 하는 포털에 대해 업데이트된 API 참조 문서를 생성합니다.

Endpoints Frameworks는 API용으로 만든 OpenAPI 문서에 설명을 포함하지 않습니다. API 사용자에게 포털 URL을 제공하기 전에 OpenAPI 문서에서 API, 메소드, 매개변수에 설명을 추가하는 것이 좋습니다.

OpenAPI를 처음 사용하는 경우에는 샘플 OpenAPI 문서를 제공하고 파일의 각 섹션을 간단하게 설명하는 Swagger 기본 구조 웹사이트부터 시작하세요. 자세한 내용은 OpenAPI 사양을 참조하세요.

메타데이터 섹션에 설명된 대로 description 필드의 값은 여러 줄을 포함할 수 있으며 GitHub 맞춤형 마크다운을 지원합니다.

사용자가 API의 메서드 사용 방법을 쉽게 이해할 수 있도록 매개변수 섹션과 요청 본문에 description 필드를 추가하는 것이 좋습니다.

OpenAPI 문서에 다음과 같은 내용이 포함됩니다.

{
 "swagger": "2.0",
 "info": {
  "version": "1.0.0",
  "title": "example-project-12345.appspot.com"
 },
 "host": "example-project-12345.appspot.com",

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

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

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

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

API에 title 필드의 값을 변경하고 description 필드를 추가하는 것이 좋습니다. 예를 들면 다음과 같습니다.

{
 "swagger": "2.0",
 "info": {
  "version": "1.0.0",
  "title": "Endpoints Frameworks Example",
  "description": "A simple Cloud Endpoints Frameworks API example."
 },
 "host": "example-project-12345.appspot.com",

SmartDocs 다시 생성

이 작업에 필요한 권한

SmartDocs를 다시 생성하려면 업데이트된 Endpoints 구성을 배포합니다. 서비스에 부여된 서비스 구성 편집자 역할은 Endpoints 구성을 다시 배포하기 위한 최소 필요 권한입니다. 이 역할을 할당하는 방법은 API에 대한 액세스 권한 부여 및 취소를 참조하세요.

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

1. Endpoints Frameworks가 생성한 openapi.json 파일을 변경합니다.

2. openapi.json을 재배포합니다.

   gcloud endpoints services deploy openapi.json
   

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

4. 나중에 openapi.json 파일을 다시 생성해야 하는 경우 수정된 openapi.json 파일을 덮어쓰지 않도록 적절한 위치에 이 파일을 저장합니다. API를 변경하고 openapi.json 파일을 다시 생성하면 새롭게 생성된 openapi.json에 이전에 변경한 내용을 병합해야 합니다.

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