Dokumentasi Inline API

Bagian ini memberikan panduan untuk menambahkan dokumentasi inline ke API Anda. Sebagian besar API juga akan memiliki ringkasan, tutorial, dan dokumentasi referensi tingkat tinggi, yang berada di luar cakupan Panduan Desain ini. Untuk mengetahui informasi tentang API, resource, dan penamaan metode, lihat Konvensi Penamaan.

Format komentar dalam file proto

Tambahkan komentar ke file .proto menggunakan format komentar // Buffering Protokol biasa.

// 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" };
}

Komentar dalam konfigurasi layanan

Selain menambahkan komentar dokumentasi ke file .proto, Anda dapat menambahkan dokumentasi inline ke API dalam file konfigurasi layanan YAML-nya. Dokumentasi dalam file ini akan lebih diprioritaskan daripada dokumentasi dalam .proto jika elemen yang sama didokumentasikan dalam kedua file.

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.
...

Anda mungkin perlu menggunakan pendekatan ini jika memiliki beberapa layanan yang menggunakan file .proto yang sama dan ingin memberikan dokumentasi khusus layanan. Aturan dokumentasi YAML juga memungkinkan Anda menambahkan overview yang lebih mendetail ke deskripsi API. Namun, secara umum, menambahkan komentar dokumentasi ke .proto lebih diutamakan.

Seperti halnya komentar .proto, Anda dapat menggunakan Markdown untuk memberikan pemformatan tambahan dalam komentar file YAML.

Deskripsi API

Deskripsi API adalah frasa yang dimulai dengan kata kerja aktif yang menjelaskan apa yang dapat Anda lakukan dengan API. Dalam file .proto Anda, deskripsi API ditambahkan sebagai komentar ke service yang sesuai, seperti dalam contoh berikut:

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

Berikut ini beberapa contoh deskripsi API lainnya:

Berbagi pembaruan, foto, video, dan lain-lain dengan teman di seluruh dunia.
Mengakses layanan machine learning yang dihosting di cloud yang memudahkan untuk mem-build aplikasi cerdas yang merespons aliran data.

Deskripsi aset

Deskripsi resource adalah kalimat parsial yang menjelaskan apa yang direpresentasikan oleh resource tersebut. Jika Anda perlu menambahkan detail, gunakan kalimat tambahan. Dalam file .proto Anda, deskripsi resource ditambahkan sebagai komentar ke jenis pesan yang sesuai, seperti dalam contoh berikut:

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

Berikut adalah beberapa contoh deskripsi resource:

Tugas di daftar tugas pengguna. Setiap tugas memiliki prioritas unik.
Acara di kalender pengguna.

Deskripsi kolom dan parameter

Frasa kata benda yang menjelaskan definisi kolom atau parameter, seperti yang ditunjukkan pada contoh berikut:

Jumlah topik dalam rangkaian ini.
Akurasi koordinat lintang dan bujur, dalam meter. Harus positif.
Tanda yang mengatur apakah nilai URL lampiran ditampilkan untuk resource pengiriman dalam rangkaian ini. Nilai default untuk series.insert adalah true.
Penampung untuk informasi pemungutan suara. Hanya ada saat informasi pemungutan suara direkam.
Saat ini tidak digunakan atau tidak digunakan lagi.

Deskripsi kolom dan parameter harus menjelaskan nilai yang valid dan tidak valid. Perlu diingat bahwa engineer akan melakukan upaya terbaik untuk merusak layanan, dan tidak akan dapat membaca kode yang mendasarinya untuk mengklarifikasi informasi yang tidak jelas.

Untuk string, deskripsi harus menjelaskan sintaksis dan karakter yang diizinkan, serta encoding apa pun yang diperlukan. Contoh:

1-255 karakter dalam himpunan [A-a0-9]
String jalur URL valid yang dimulai dengan / yang mengikuti konvensi RFC 2332. Panjang maksimal adalah 500 karakter.

Deskripsi harus menentukan nilai atau perilaku default apa pun, tetapi mungkin tidak menjelaskan nilai default yang pada dasarnya adalah null.

Jika nilai kolom bersifat wajib, hanya input, dan hanya output, nilai tersebut harus didokumentasikan di awal deskripsi kolom. Secara default, semua kolom dan parameter bersifat opsional. Contoh:

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;
}

Deskripsi metode

Deskripsi metode adalah kalimat yang menunjukkan efek yang dimiliki metode dan resource yang mengoperasikannya. Ini biasanya dimulai dengan kata kerja orang ketiga, present tense, mis., dalam bahasa Inggris, kata kerja yang berakhiran "s". Jika Anda perlu menambahkan lebih detail, gunakan kalimat tambahan. Berikut beberapa contohnya:

Mencantumkan acara kalender untuk pengguna yang diautentikasi.
Memperbarui acara kalender dengan data yang disertakan dalam permintaan.
Menghapus data lokasi dari histori lokasi pengguna yang diautentikasi.
Membuat atau memperbarui catatan lokasi di histori lokasi pengguna yang diautentikasi menggunakan data yang disertakan dalam permintaan. Jika resource lokasi sudah ada dengan nilai stempel waktu yang sama, data yang diberikan akan menimpa data yang ada.

Checklist untuk semua deskripsi

Pastikan setiap deskripsi singkat, tetapi lengkap, dan dapat dipahami oleh pengguna yang tidak memiliki informasi tambahan tentang API. Dalam kebanyakan kasus, ada banyak hal yang perlu disampaikan selain sekadar menyatakan kembali hal yang sudah jelas; misalnya, deskripsi metode series.insert tidak boleh hanya menyatakan "Menyisipkan rangkaian". — meskipun penamaan Anda harus informatif, sebagian besar pembaca membaca deskripsi karena mereka menginginkan lebih banyak informasi daripada nama itu sendiri. Jika Anda tidak yakin apa lagi yang harus dikatakan dalam deskripsi, coba jawab semua pertanyaan berikut yang relevan:

Apa ini?
Apa yang akan dilakukan jika berhasil? Apa yang akan dilakukan jika gagal? Apa yang dapat menyebabkannya gagal, dan bagaimana?
Apakah bersifat idempoten?
Apa saja satuannya? (Contoh: meter, derajat, piksel.)
Berapa kisaran nilai yang diterima? Apakah rentang tersebut inklusif atau eksklusif?
Apa saja efek sampingnya?
Bagaimana cara menggunakannya?
Kesalahan umum apa yang dapat menyebabkannya rusak?
Apakah selalu ada? (Misalnya: "Penampung untuk informasi pemilihan suara. Ditampilkan hanya saat informasi pemungutan suara direkam.")
Apakah alat ini memiliki setelan default?

Konvensi

Bagian ini mencantumkan beberapa konvensi penggunaan untuk deskripsi dan dokumentasi tekstual. Misalnya, gunakan "ID" (huruf besar semua), bukan "ID" atau "id" saat membahas ID. Gunakan "JSON" bukan "Json" atau "json" saat merujuk ke format data tersebut. Tampilkan semua nama kolom/parameter di code font. Masukkan nilai string literal di code font dan tanda kutip.

ID
JSON
RPC
REST
property_name atau "string_literal"
true/false

Tingkat persyaratan

Untuk menetapkan ekspektasi atau tingkat persyaratan status, gunakan istilah: harus, tidak boleh, wajib, harus, tidak boleh, harus, tidak boleh, direkomendasikan, mungkin, dan opsional.

Artinya didefinisikan dalam RFC 2119. Anda mungkin ingin menyertakan pernyataan dari abstrak RFC dalam dokumentasi API.

Tentukan istilah yang memenuhi persyaratan Anda sekaligus memberi developer fleksibilitas. Jangan gunakan istilah absolut seperti harus ketika opsi lain secara teknis berfungsi di API Anda.

Gaya bahasa

Seperti dalam konvensi penamaan kami, sebaiknya gunakan kosakata dan gaya yang sederhana dan konsisten saat menulis komentar dokumen. Komentar harus dapat dipahami oleh pembaca yang tidak berbicara dalam bahasa Inggris, jadi hindari jargon, bahasa gaul, metafora yang kompleks, referensi budaya pop, atau apa pun yang sulit diterjemahkan. Gunakan gaya yang ramah dan profesional yang berbicara langsung kepada developer yang membaca komentar Anda, dan tuliskan sesingkat mungkin. Ingat, sebagian besar pembaca ingin mengetahui cara melakukan sesuatu dengan API Anda, bukan membaca dokumentasi Anda.