API 문서화에 대한 지침과 스타일, 설명 작성법, 서식, 상호 참조, 외부 링크, 상표명, 사용 중단, 내부 주석 규칙을 설명합니다.
범위별 AIP
AIP
문서화는 API 설계에서 가장 중요한 측면 중 하나입니다. API 사용자는 API를 더 잘 이해하기 위해 구현 내부를 파고들 수 없으며, 많은 경우 API 표면 정의와 그에 대응하는 문서만이 사용자가 가지는 전부입니다. 따라서 문서화는 가능한 한 명확하고, 완전하며, 모호하지 않도록 하는 것이 중요합니다.
프로토콜 버퍼로 정의된 API에서는 모든 구성 요소(서비스, 메서드, 메시지, 필드, enum, enum 값) 위에 프로토콜 버퍼 주석 형식을 사용한 공개 주석을 반드시 포함해야 합니다. 이는 주석이 짧고 흥미롭지 않은 경우에도 중요합니다. 이러한 주석을 읽고 활용하는 도구가 많기 때문입니다.
특히 서비스에는 해당 서비스가 무엇이며 사용자가 그것으로 무엇을 할 수 있는지 설명하는 서술형 주석이 권장됩니다.
참고: 많은 독자는 영어 원어민이 아닐 수 있습니다. 주석은 가급적 전문 용어, 속어, 복잡한 비유, 대중문화 참조, 또는 쉽게 번역되지 않는 다른 표현을 피해야 합니다. 또한 많은 독자는 서로 다른 배경과 관점을 가지고 있습니다. 사람을 등장시키는 예시를 작성한다면, 주석은 가급적 논란의 여지가 없고 현재 생존해 있지 않은 사람을 사용해야 합니다.
주석은 문법적으로 올바른 미국식 영어로 작성하는 것이 권장됩니다. 그러나 각 주석의 첫 문장은 주어를 생략하고 3인칭 현재 시제로 작성하는 것이 권장됩니다:
// Creates a book under the given publisher.
rpc CreateBook(CreateBookRequest) returns (Book) {
option (google.api.http) = {
post: "/v1/{parent=publishers/*}/books"
body: "book"
};
}
메시지와 필드에 대한 설명은 짧지만 완전한 것이 권장됩니다. 때로는 할 말이 거의 없어서 주석이 형식적일 수밖에 없지만, 그렇게 결론내리기 전에 다음 질문 중 일부가 관련 있는지 고려하십시오:
이것은 무엇인가?
이것은 어떻게 사용하는가?
성공하면 무엇을 하는가? 실패하면 무엇을 하는가?
멱등적인가?
단위는 무엇인가? (예: 미터, 도, 픽셀)
부작용은 무엇인가?
이를 깨뜨릴 수 있는 일반적인 오류는 무엇인가?
예상 입력 형식은 무엇인가?
허용하는 값의 범위는 무엇인가? (예: [0.0, 1.0), [1, 10])
문자열의 경우 최소 길이와 최대 길이는 얼마이며, 어떤 문자가 허용되는가?
항상 존재하는가? (예: "투표 정보용 컨테이너. 투표 정보가 기록된 경우에만 존재함.")
기본 설정이 있는가? (예: "page_size가 생략되면 기본값은 50임.")
주석 내의 모든 서식은 CommonMark여야 합니다. 제목과 표는 여러 도구에서 문제를 일으키고 클라이언트 라이브러리 참조 문서에도 적합하지 않으므로 사용해서는 안 됩니다.
주석은 필드명이나 메서드명, 그리고 true와 같은 리터럴에 코드 글꼴을 사용하는 것이 권장됩니다.
원시 HTML은 사용해서는 안 됩니다.
protos 안에서 다이어그램을 표현하려는 "ASCII art" 시도는 사용해서는 안 됩니다. protos 안의 Markdown은 매우 많은 렌더러에서 소비되며, ASCII art는 그 모두에서 잘 표현될 가능성이 매우 낮습니다. API를 이해하기 위해 다이어그램이 유용하다면, 다이어그램이 이미지로 포함된 문서 페이지 링크를 대신 포함하십시오.
주석은 Markdown 참조 링크로 다른 구성 요소(서비스, 메서드, 메시지, 필드, enum, enum 값)에 "링크"할 수 있습니다. 참조는 반드시 다음 형식 중 하나여야 합니다:
[Book][google.example.v1.Book][Sci-Fi genre][Genre.GENRE_SCI_FI][Book][] 이는 [Book][Book]와 동일함이 참조들은 이름 해석 규칙에 따라 해석됩니다.
포함하는 필드 이름은 참조에 사용해서는 안 됩니다. 해석되지 않기 때문입니다. 대신 원래 정의를 반드시 참조해야 합니다. 예를 들어 author가 Book의 필드인 경우, [author][Book.author.family_name]는 해석되지 않지만 [author][Author.family_name]는 해석됩니다.
주석은 공개 주석 자체에 설명된 범위를 넘어서는 배경 정보를 제공하기 위해 외부 페이지에 링크할 수 있습니다. 외부 링크는 프로토콜(보통 https)을 포함한 절대 URL을 반드시 사용해야 하며, 문서가 특정 호스트에 위치한다고 가정해서는 안 됩니다. 예: [Spanner Documentation](https://cloud.google.com/spanner/docs)
주석에서 회사나 제품의 고유한 상표명을 언급할 때는, 그 약어를 피하면 오히려 참조가 불분명해질 정도로 일상적으로 지배적인 경우가 아니라면(예: IBM) 약어를 사용하지 않는 것이 권장됩니다.
주석은 상표권자의 현재 브랜딩에 맞게 상표명을 표기하고 대문자 사용을 맞추는 것이 권장됩니다.
구성 요소(서비스, 메서드, 메시지, 필드, enum, enum 값)를 사용 중단하려면 deprecated option을 반드시 true로 설정해야 하며, 해당 주석의 첫 줄은 반드시 "Deprecated: "로 시작하고 개발자를 위한 대체 해결책을 제공해야 합니다. 대체 해결책이 없다면, 사용 중단 이유를 반드시 제공해야 합니다.
주석은 내부 콘텐츠를 (--와 --)로 감싸 명시적으로 내부용으로 표시할 수 있습니다.
비공개 링크, 내부 구현 메모(TODO, FIXME 지시어 등), 그리고 그 밖의 이러한 자료는 반드시 내부용으로 표시해야 합니다.
참고: 주석은 선행 주석만 사용하고(후행 주석이나 분리된 주석은 사용하지 않고) 작성하는 것이 권장됩니다. 특히 어떤 구성 요소를 설명하기 위해 선행 주석과 후행 주석을 모두 사용해서는 안 됩니다. 이는 내부 콘텐츠 주석 표시가 의도치 않게 누락되는 흔한 원인이기 때문입니다.