API 사용자에게 포털 URL을 제공하기 전에 SmartDocs API 참조 문서가 올바르고 API가 문서에 작성된 대로 동작하는지 확인하세요. 생성된 참조 문서와 테스트를 검토하다 보면 변경하고 싶은 내용이 보일 수 있습니다.
이 페이지에서는 다음 주제에 대해 설명합니다.- SmartDocs API 참조 문서
- SmartDocs가
.proto및 서비스 구성 파일의 필드 및 주석을 사용하여 SmartDocs를 생성하는 방법 - SmartDocs를 다시 생성하는 방법
기본 요건
이 페이지에서는 이미 포털을 만들었다고 가정합니다.
SmartDocs API 참조 문서 정보
Endpoints 서비스에 서비스 구성을 배포할 때마다 SmartDocs는 해당 포털에 대해 API 참조 문서를 생성합니다. SmartDocs UI는 최첨단 UI 구성요소 라이브러리인 Angular Material을 기반으로 합니다. 개발자는 SmartDocs API 참조 문서를 검토하고 API 사용해 보기 위젯을 사용하여 API 문서에서 나가지 않고 API와 상호작용할 수 있습니다.SmartDocs 생성에 사용되는 필드 정보
서비스 구성 파일(api_config.yaml)에는 다음과 같은 내용이 포함되어 있습니다.
title: Bookstore gRPC API apis: - name: endpoints.examples.bookstore.Bookstore
title: title의 값은 포털 홈페이지에서 프로젝트의 API가 나열된 섹션, API 홈페이지(documentation이라는 단어가 붙음), API 제목 표시줄에 표시됩니다.name: Endpoints 서비스의 이름이기도 한name값은 포털 홈페이지에서 프로젝트의 API가 나열된 섹션 및 설정 페이지에서 API 탭에 표시되는 드롭다운 목록에 표시됩니다.
Endpoints 포털은 .proto 파일에 있는 각 RPC 메서드와 리소스에 대한 참조 문서를 생성합니다. 각 메소드 및 리소스와 연결된 주석은 포털에 표시되는 문서에 포함됩니다. 다음 항목은 Endpoints 포털 데모의 Bookstore gRPC API 예에 대한 참조 문서를 생성하기 위해 사용된 .proto 파일에서 가져온 것입니다.
service Bookstore {
// Returns a list of all shelves in the bookstore.
rpc ListShelves(google.protobuf.Empty) returns (ListShelvesResponse) {}
// Creates a new shelf in the bookstore.
rpc CreateShelf(CreateShelfRequest) returns (Shelf) {}
// Returns a specific bookstore shelf.
rpc GetShelf(GetShelfRequest) returns (Shelf) {}
// Deletes a shelf, including all books that are stored on the shelf.
rpc DeleteShelf(DeleteShelfRequest) returns (google.protobuf.Empty) {}
// Returns a list of books on a shelf.
rpc ListBooks(ListBooksRequest) returns (ListBooksResponse) {}
// Creates a new book.
rpc CreateBook(CreateBookRequest) returns (Book) {}
// Returns a specific book.
rpc GetBook(GetBookRequest) returns (Book) {}
// Deletes a book from a shelf.
rpc DeleteBook(DeleteBookRequest) returns (google.protobuf.Empty) {}
}
Endpoints 포털 데모에 사용된 전체 bookstore.proto 파일은 bookstore-grpc Endpoints 샘플에 있습니다.
SmartDocs 다시 생성
참조 문서를 다시 생성하려면 다음 안내를 따르세요.
서비스 구성 또는 사용자의
.proto파일에 변경사항을 적용합니다..proto파일을 변경한 경우 프로토콜 버퍼를 컴파일합니다..pb파일 및 서비스 구성 파일을 다시 배포합니다. 예를 들면 다음과 같습니다.gcloud endpoints services deploy api_descriptor.pb api_config.yaml포털 페이지를 새로고칩니다.
명령어에 대한 자세한 내용은 gcloud endpoints services deploy를 참조하세요.