Hai! Saya pemasok API (Bahan Farmasi Aktif), dan hari ini saya ingin ngobrol tentang cara mendokumentasikan API menggunakan OpenAPI. Ini sangat penting dalam pekerjaan kami, karena dokumentasi yang jelas dapat menentukan keberhasilan atau kegagalan API kami.
Pertama, mari kita pahami apa itu OpenAPI. OpenAPI adalah spesifikasi standar terbuka untuk mendeskripsikan RESTful API. Ini menyediakan cara untuk menentukan titik akhir, operasi, data input dan output, dan persyaratan keamanan API dalam format yang dapat dibaca mesin. Ini berarti pengembang lain dapat dengan mudah memahami dan mengintegrasikan API kami ke dalam aplikasi mereka.
Mengapa Mendokumentasikan API dengan OpenAPI Penting
Sebagai pemasok API, kami memiliki banyak produk hebat sepertiMemantin Hidroklorida丨CAS 41100 - 52 - 1,Desoksimetason丨CAS 382-67-2, DanGlutathione丨CAS 70-18-8. Untuk memudahkan pelanggan kami mengakses dan menggunakan API ini, dokumentasi yang tepat adalah suatu keharusan.
Saat kami mendokumentasikan API kami dengan OpenAPI, ada beberapa hal yang membantu. Pertama, ini memungkinkan kami berkomunikasi secara jelas dengan pelanggan tentang apa yang dapat dilakukan API kami. Mereka dapat melihat dengan tepat titik akhir apa yang tersedia, parameter apa yang harus mereka lewati, dan respons seperti apa yang dapat mereka harapkan. Hal ini mengurangi jumlah pertanyaan dan kesalahpahaman, yang pada akhirnya menghemat waktu bagi kami dan pelanggan kami.
Manfaat lainnya adalah meningkatkan interoperabilitas. Karena OpenAPI adalah standar terbuka, banyak alat dan kerangka kerja yang mendukungnya. Ini berarti pengembang dapat menggunakan berbagai alat untuk menghasilkan kode klien, menguji API kami, dan bahkan memvisualisasikan struktur API. Hal ini memudahkan mereka untuk mengintegrasikan API kami ke dalam sistem mereka yang sudah ada.
Memulai Dokumentasi OpenAPI
Langkah pertama dalam mendokumentasikan API menggunakan OpenAPI adalah mendefinisikan informasi dasar tentang API. Ini termasuk judul, deskripsi, versi, dan informasi kontak API. Anda dapat menganggap ini sebagai "metadata" API. Misalnya, Anda mungkin mengatakan sesuatu seperti:
openapi: 3.0.0 info: title: API kami untuk Bahan Farmasi deskripsi: API ini menyediakan akses ke informasi tentang berbagai bahan aktif farmasi kami. versi: 1.0.0 kontak: nama: API Dukungan email: support@example.comSelanjutnya, Anda perlu menentukan server tempat API dihosting. Ini memberi tahu pengembang di mana mereka sebenarnya dapat membuat permintaan ke API. Anda dapat menentukan beberapa server, misalnya, server produksi dan server pengujian.
server: - url: https://api.example.com/v1 deskripsi: Server produksi - url: https://test-api.example.com/v1 deskripsi: Server pengujianMendefinisikan Jalur dan Operasi API
Inti dari dokumen OpenAPI adalah definisi jalur dan operasi API. Jalur mewakili titik akhir tertentu di API, dan operasi adalah tindakan yang dapat dilakukan pada titik akhir tersebut, seperti GET, POST, PUT, atau DELETE.
Katakanlah kita memiliki API yang memberikan informasi tentang bahan-bahan farmasi kita. Kita mungkin memiliki jalan seperti itu/bahan-bahanuntuk mendapatkan daftar semua bahan yang tersedia.
jalur: /bahan: dapatkan: ringkasan: Dapatkan daftar semua bahan farmasi deskripsi: Mengembalikan daftar semua bahan aktif farmasi yang kami tawarkan. tanggapan: '200': deskripsi: Daftar bahan konten: aplikasi/json: skema: tipe: item array: tipe: properti objek: nama: tipe: string cas_number: tipe: stringDalam contoh ini, kami telah mendefinisikan operasi GET pada/bahan-bahanjalur. Ringkasan dan deskripsi memberikan informasi lebih lanjut tentang apa yang dilakukan operasi. Bagian tanggapan menentukan apa yang akan dikembalikan API ketika operasi berhasil (kode status 200). Dalam hal ini, ia mengembalikan array objek JSON, di mana setiap objek mewakili bahan dengan nama dan nomor CAS.
Menangani Parameter Masukan
Banyak operasi API memerlukan parameter masukan. Ini bisa berupa parameter kueri (dikirim dalam URL), parameter jalur (bagian dari URL), atau parameter isi permintaan (dikirim dalam isi permintaan).
Katakanlah kita ingin mendapatkan informasi tentang bahan tertentu berdasarkan nomor CAS-nya. Kita dapat menentukan parameter jalur untuk ini.
path: /ingredients/{cas_number}: get: ringkasan: Dapatkan informasi tentang deskripsi bahan tertentu: Mengembalikan informasi terperinci tentang suatu bahan berdasarkan nomor CAS-nya. parameter: - nama: cas_number di: deskripsi jalur: Nomor CAS bahan yang dibutuhkan: true skema: tipe: string tanggapan: '200': deskripsi: Informasi tentang konten bahan: aplikasi/json: skema: tipe: properti objek: nama: tipe: string nomor_cas: tipe: string deskripsi: tipe: stringDalam contoh ini, kami telah mendefinisikan parameter jalurcas_numberdi/bahan/{cas_number}jalur. Itudiperlukanbidang menunjukkan bahwa parameter ini harus disediakan saat membuat permintaan.
Keamanan dan Otentikasi
Keamanan adalah aspek penting dari API apa pun. OpenAPI memungkinkan Anda menentukan persyaratan keamanan untuk operasi API Anda. Anda dapat menentukan hal-hal seperti kunci API, OAuth 2.0, atau autentikasi dasar.
Misalnya, jika API kita menggunakan kunci API untuk autentikasi, kita dapat mendefinisikannya seperti ini:
komponen: skema keamanan: api_key: ketik: apiKey nama: X - API - Masukkan: header keamanan: - api_key: []Dalam contoh ini, kami telah mendefinisikan skema keamanan yang disebutapi_keyyang menggunakan kunci API yang dikirim dalamX - API - Kuncitajuk. Itukeamananbagian di tingkat atas dokumen menunjukkan bahwa semua operasi di API memerlukan kunci API ini untuk otentikasi.
Memvalidasi dan Menguji Dokumen OpenAPI
Setelah Anda membuat dokumen OpenAPI, penting untuk memvalidasinya untuk memastikan dokumen tersebut mengikuti spesifikasi OpenAPI. Ada banyak alat online yang tersedia yang dapat membantu Anda dalam hal ini. Anda juga dapat menggunakan alat untuk menghasilkan kode klien dari dokumen OpenAPI dan menguji API.
Pengujian sangat penting untuk memastikan bahwa API berfungsi seperti yang diharapkan. Anda dapat menggunakan alat seperti Tukang Pos atau cURL untuk mengirim permintaan ke API dan memverifikasi tanggapannya. Dengan menguji API dengan parameter dan skenario masukan yang berbeda, Anda dapat mengetahui bug atau masalah apa pun sejak dini.
Kesimpulan dan Ajakan Bertindak
Mendokumentasikan API menggunakan OpenAPI adalah cara ampuh untuk membuat API Anda lebih mudah diakses dan ramah pengguna. Sebagai pemasok API, ini membantu kami melayani pelanggan dengan lebih baik dan mempromosikan penggunaan produk seperti kamiMemantin Hidroklorida丨CAS 41100 - 52 - 1,Desoksimetason丨CAS 382-67-2, DanGlutathione丨CAS 70-18-8.
Jika Anda tertarik untuk mempelajari lebih lanjut tentang API kami atau memiliki pertanyaan tentang dokumentasi, silakan menghubungi kami. Kami selalu dengan senang hati mendiskusikan potensi kemitraan dan membantu Anda mengintegrasikan API kami ke dalam proyek Anda. Baik Anda perusahaan rintisan kecil atau perusahaan farmasi besar, API kami dapat memberikan informasi berharga tentang bahan farmasi kami yang berkualitas tinggi.
Referensi
- Dokumentasi Spesifikasi OpenAPI
- Swagger.io - Alat dan Sumber Daya untuk OpenAPI
- Dokumentasi Tukang Pos untuk Pengujian API
