Tentunya, selama pengembangan API, kesulitan dengan dokumentasi muncul lebih dari sekali: baik itu tidak ada, maka tidak menampilkan perilaku yang dijelaskan dalam kode.
Dari sudut pandang pengembang, menulis dokumentasi (hanya internal) tidak kurang dari waktu menulis kode itu sendiri. Apakah itu familier? Kemudian selamat datang di kucing.
Apakah ada masalah?
Tim kami telah mengembangkan API untuk waktu yang lama, yang merupakan dasar dari produk kami, tetapi pada saat itu tidak ada pengguna langsung, jadi tidak ada yang melihat kebutuhan untuk mendokumentasikan sesuatu untuk penggunaan eksternal. Seperti semua tim, kami mulai dengan dokumentasi internal - pertama metode, lalu yang lain. Di ruang kami di Confluence, Anda dapat menemukan selusin halaman lain yang menampilkan informasi yang sangat sederhana - seperti apa metode API, jalur kueri apa yang dimilikinya, parameter apa dan apa yang kami dapatkan di output.
Semuanya akan baik-baik saja, tetapi kode terus berubah dan berkembang, kebutuhan bisnis berubah. Seiring dengan perubahan kode, API dapat berubah, yang pasti mengarah pada perubahan pada halaman ini. Nah, kalau itu satu halaman dan hanya 1 kali saja. Dan jika ada lebih banyak perubahan?
Kami datang dengan solusi (sepeda kami sendiri), sebanyak mungkin, sambil terlibat dalam kegiatan pengembang yang biasa, tidak berpikir tentang menulis dan memperbarui dokumentasi internal.
Beberapa solusi
Ada beberapa pilihan untuk bagaimana kode dan spesifikasinya dapat saling berhubungan, tetapi untuk saya sendiri saya membedakan dua:
- Kode pertama, spesifikasi selanjutnya
- Spesifikasi pertama, kode selanjutnya
Saya akan mulai dengan yang kedua, karena dengan opsi yang paling tidak cocok untuk kita.
Spesifikasi pertama, kode berikutnya adalah tentang pembuatan kode, berdasarkan spesifikasi, yaitu, kode tidak ada sampai Anda menulis spesifikasi.
Contoh paling sederhana adalah Swagger Codegen.
Perusahaan kami memiliki tim yang menggunakan pendekatan ini dalam produk mereka, tetapi dalam kasus kami itu tidak terlalu cocok. Pada saat kami dihadapkan dengan suatu kebutuhan, kami telah menulis banyak metode API, jadi demi dokumentasi kami tidak ingin secara radikal mengubah proses pengembangan - pertama kami menulis konsep, kemudian kami kode dan hanya kemudian deskripsi spesifikasi.
Kode pertama, spesifikasi berikutnya - semuanya sederhana, pertama kita menulis kode, kemudian spesifikasinya. Tetapi kemudian muncul pertanyaan - dan jika kita tidak ingin membuat gerakan yang tidak perlu sehingga spesifikasi dihasilkan?
Sejumlah aplikasi di perusahaan kami menggunakan pendekatan ini, tetapi tidak terlalu otomatis - metode API dibobot dengan semua jenis anotasi, berdasarkan spesifikasi yang dihasilkan. Tetapi penjelasan yang sama ini seringkali tidak sesuai dengan kenyataan, karena kebutuhan dan kemampuan aplikasi tumbuh dan berubah.
"Kamu adalah seorang programmer," kataku pada diriku sendiri, dan memutuskan untuk menulis prototipe kecil yang memungkinkan aku untuk tidak menulis semua sampah rutin ini.
Membuat tugas selanjutnya dan menulis tes fungsional ke-n, saya menyadari bahwa kita sudah memiliki semua informasi untuk spesifikasi.
Kami memiliki tes fungsional yang berisi hampir semua informasi yang kami butuhkan:
- Apa yang dipanggil
- Apa yang disebut (parameter, tubuh, tajuk, dll.)
- Apa hasil yang diharapkan (kode status, badan respons)
Mengapa tidak membuat sepeda sendiri?
Hampir semua yang biasa kita tuliskan dalam spesifikasi yang kita miliki. Kasing untuk kode kecil kasing ini.
Karena aplikasi kami ada di php, refleksi datang membantu saya. Menggunakan sedikit keajaiban refleksi, kami mengumpulkan semua metode API yang tersedia untuk kami, mengambil data dari tes fungsional, mengekstrak data tentang otorisasi dan jenisnya. Dari anotasi biasa ke metode, kita mendapatkan deskripsi dari metode itu sendiri. Setelah mencampuradukkan semua ini, membumbui dengan fitur spesifik untuk kerangka kerja yang digunakan dalam solusi kami, dalam beberapa minggu kami mendapatkan solusi yang secara praktis tidak memerlukan waktu tambahan dari pengembang.
Membuat spesifikasi hanya langkah pertama - Anda perlu mendapatkan dokumentasi dari spesifikasi yang dapat disediakan oleh pengembang eksternal. Salah satu syarat untuk dokumentasi adalah harus disajikan dalam beberapa bahasa, tetapi saat ini, kami hanya menghasilkan dokumentasi dalam bahasa Inggris. Sejauh ini, cukup, tetapi akan diperlukan untuk menghubungkan mekanisme untuk menerima transfer ke skema pembuatan spesifikasi kami.
Masalah yang awalnya kami pecahkan. Tetapi dengan solusi ini ada banyak risiko:
- Harga mendukung sepeda Anda sendiri
- Perpanjangan fungsi yang diperlukan
- Perbarui dan sinkronisasi terjemahan
Risiko-risiko ini harus diingat dan, jika mulai bekerja, maka ambil tindakan.