Файловая структура
API gRPC должны быть определены в .proto
файлах с использованием proto3 IDL.
Структура файла должна содержать более высокоуровневые и более важные определения до более низкого уровня и менее важных элементов. В каждом proto-файле соответствующие разделы должны быть в следующем порядке:
- Авторские права и лицензии, если необходимо.
- Proto
syntax
,package
,option
иimport
в таком порядке - Обзорная документация API, которая подготавливает читателей к остальной части файла
- Определения API proto
service
в порядке убывания важности - Определения запроса и ответа RPC
message
в том же порядке соответствующих методов. Каждое сообщение запроса должно предшествовать соответствующему ответному сообщению, если оно есть - Определения ресурсов
message
. Родительский ресурс должен быть определен до его дочерних ресурсов - ДЛя всех пролей без исключения нужно написать документацию. Помните, что ее будут читать не те, кто делает этот API. Постарайтесь емко и по сути дать описание полю.
Если один proto-файл содержит всё API, он должен быть назван в честь API.
API | Proto |
---|---|
Library | library.proto |
AccountManager | accountmanager.proto |