인라인 API 문서

이 섹션에서는 API에 인라인 문서를 추가하는 데 사용되는 가이드라인을 제공합니다. 대부분 API에는 개요, 튜토리얼, 높은 수준의 참조 문서가 있지만 이 디자인 가이드의 범위에는 포함되지 않습니다. API, 리소스, 메서드 이름 지정에 대한 자세한 내용은 이름 지정 규칙을 참조하세요.

proto 파일의 주석 형식

일반적인 프로토콜 버퍼 // 주석 형식을 사용하여 명령어를 .proto 파일에 추가합니다.

// Creates a shelf in the library, and returns the new Shelf.
rpc CreateShelf(CreateShelfRequest) returns (Shelf) {
  option (google.api.http) = { post: "/v1/shelves" body: "shelf" };
}

서비스 구성 파일의 주석

.proto 파일에 문서 주석을 추가하는 방법의 대안으로 YAML 서비스 구성 파일에서 인라인 문서를 API에 추가할 수 있습니다. 동일한 요소가 두 파일에 모두 명시되어 있으면 이 파일의 문서가 .proto 파일의 문서보다 우선 적용됩니다.

documentation:
  summary: Gets and lists social activities
  overview: A simple example service that lets you get and list possible social activities
  rules:
  - selector: google.social.Social.GetActivity
    description: Gets a social activity. If the activity does not exist, returns Code.NOT_FOUND.
...

동일한 .proto 파일을 사용하는 서비스가 많아서 서비스별로 문서를 제공하려면 이 방법을 사용해야 할 수도 있습니다. 또한 YAML 문서 규칙에서는 overview를 API 설명에 더욱 자세하게 추가할 수 있습니다. 하지만 일반적으로 .proto에 문서 주석을 추가하는 것이 좋습니다.

.proto 주석을 사용할 때와 마찬가지로 마크다운을 사용하여 YAML 파일 주석에 추가 형식을 지정할 수 있습니다.

API 설명

API 설명은 능동형 동사로 시작되면서 API에서 할 수 있는 작업을 설명하는 어구입니다. .proto 파일에서는 API 설명이 아래 예시와 같이 해당 service에 주석으로 추가됩니다.

// Manages books and shelves in a simple digital library.
service LibraryService {
...
}

그 밖에 가능한 API 설명은 다음과 같습니다.

Shares updates, photos, videos, and more with your friends around the world.
Accesses a cloud-hosted machine learning service that makes it easy to build smart apps that respond to streams of data.

리소스 설명

리소스 설명은 리소스가 나타내는 것을 설명하는 구문입니다. 세부 정보를 더욱 자세하게 작성해야 할 경우에는 문장을 추가로 사용할 수 있습니다. .proto 파일에서는 리소스 설명이 아래 예시와 같이 해당 메시지 유형에 주석으로 추가됩니다.

// A book resource in the Library API.
message Book {
  ...
}

그 밖에 가능한 리소스 설명 예시는 다음과 같습니다.

A task on the user's to-do list. Each task has a unique priority.
An event on the user's calendar.

필드 및 매개변수 설명

다음 예와 같이 필드 또는 매개변수 정의를 설명하는 명사구입니다.

The number of topics in this series.
The accuracy of the latitude and longitude coordinates, in meters. Must be non-negative.
Flag governing whether attachment URL values are returned for submission resources in this series. The default value for series.insert is true.
The container for voting information. Present only when voting information is recorded.
Not currently used or deprecated.

필드 및 매개변수 설명에서 유효하고 유효하지 않은 값을 설명해야 합니다. 엔지니어는 어떤 서비스든 중단하기 위해 최선을 다할 것이며, 명확하지 않은 정보를 규명하기 위해 기본 코드를 읽어볼 수 없다는 것을 기억해야 합니다.

문자열의 경우 설명에서 구문과 허용되는 문자, 필수 인코딩을 설명해야 합니다. 예를 들면 다음과 같습니다.

1-255 characters in the set [A-a0-9]
RFC 2332 규칙을 따르는 /로 시작하는 유효한 URL 경로 문자열입니다. Max length is 500 characters.

설명에 기본 값 또는 동작을 지정해야 하지만 실질적으로 무효인 값을 설명하는 것은 생략할 수 있습니다.

필드 값이 필요하다면 필드 설명을 시작할 때 input only 또는 output only를 입력해야 합니다. 기본적으로 모든 필드 및 매개변수는 선택사항입니다. 예를 들면 다음과 같습니다.

message Table {
  // Required. The resource name of the table.
  string name = 1;

  // Input only. Whether to validate table creation without actually doing it.
  bool validate_only = 2;

  // Output only. The timestamp when the table was created. Assigned by
  // the server.
  google.protobuf.Timestamp create_time = 3;

  // The display name of the table.
  string display_name = 4;
}

메서드 설명

메서드 설명은 메서드의 효과와 메서드가 실행되는 리소스를 나타내는 문장입니다. 일반적으로 3인칭 현재 시제의 동사, 즉 영어의 경우 's'로 끝나는 동사로 시작됩니다. 세부정보를 더욱 자세하게 작성해야 할 경우에는 추가 문장을 사용합니다. 예시

Lists calendar events for the authenticated user.
Updates a calendar event with the data included in the request.
Deletes a location record from the authenticated user's location history.
Creates or updates a location record in the authenticated user's location history using the data included in the request. If a location resource already exists with the same timestamp value, the data provided overwrites the existing data.

모든 설명에 대한 체크리스트

각 설명은 간략하지만 완전해야 하고 API에 대한 추가 정보가 없는 사용자도 이해할 수 있어야 합니다. 대부분의 경우 뻔한 내용을 다시 말하는 것보다는 해야 할 말이 더욱 많습니다. 예를 들어 series.insert 메서드 설명은 단순히 'Inserts a series'가 되어서는 안 됩니다. 지정하는 이름이 유용해야 하는 것은 사실이지만 대부분 개발자들이 설명을 읽는 이유는 이름 자체의 의미보다 더 많은 정보를 원하기 때문입니다. 설명에서 이름 외에 어떤 말을 해야 할지 모를 경우에는 다음과 같이 관련된 질문에 대한 답변을 생각해보세요.

무엇에 대한 설명입니까?
성공하면 어떻게 됩니까? 실패하면 어떻게 됩니까? 실패하게 되는 원인과 방법은 무엇입니까?
멱등성을 갖습니까?
단위(예: meter, degree, pixel)는 무엇입니까?
값의 범위는 어디까지 허용됩니까? 포괄적 범위입니까? 아니면 배타적 범위입니까?
부작용은 무엇입니까?
사용하려면 어떻게 해야 합니까?
위반할 수 있는 공통 오류는 무엇입니까?
항상 존재합니까? (예: 'Container for voting information. Present only when voting information is recorded.')
기본 설정이 있습니까?

규칙

이번 섹션에서는 텍스트 설명 및 문서에 대한 사용 규칙에 대해서 설명합니다. 예를 들어 식별자에 대해서 얘기할 때는 'Id' 또는 'id'가 아닌 'ID'(모두 대문자)를 사용합니다. 데이터 형식을 언급할 때는 'Json' 또는 'json'보다는 'JSON'을 사용합니다. 필드/매개변수 이름 모두 code font 형식으로 표시합니다. 리터럴 문자 값을 따옴표 사이 code font 형식으로 입력합니다.

ID
JSON
RPC
REST
property_name 또는 "string_literal"
true/false

요구사항 수준

기대치를 설정하거나 요구사항 수준을 언급할 때는 must, must not, required, shall, shall not, should, should not, recommended, may, optional 등과 같은 표현을 사용하세요.

각 의미는 RFC 2119에 설명되어 있습니다. RFC 초록의 문장을 API 문서에 추가할 수도 있습니다.

어떤 표현이 요구사항에 적합한 동시에 개발자에게 유연성까지 제공할 수 있는지 결정하세요. API에서 다른 선택사항이 기술적으로 유효한 경우에는 must 같이 절대적인 표현을 사용해서는 안 됩니다.

언어 스타일

이름 지정 규칙에서 그랬던 것처럼 문서 주석을 작성할 때도 간단하고 일관적인 어휘와 스타일을 사용하는 것이 좋습니다. 영어를 모국어로 사용하지 않는 개발자들도 주석을 이해할 수 있도록 전문 용어, 비속어, 복잡한 비유, 대중 문화 인용, 혹은 그 밖에 쉽게 번역되지 않는 표현을 사용해서는 안 됩니다. 주석을 읽는 개발자들에게 직접 얘기하듯이 친숙하고 전문적인 스타일을 사용하고, 최대한 간결한 표현을 유지하세요. 대부분 개발자들은 API를 사용하는 작업 방법에 대해서 알고 싶어할 뿐 단순히 문서를 읽으려고 하는 것은 아닙니다.

설계 패턴

proto3 사용