Apakah Anda membutuhkan bantuan dalam mengembangkan dan mendokumentasikan API untuk proyek besar atau kompleks? Jangan khawatir! Kami punya solusi yang tepat untuk Anda - OpenAPI Specification (sebelumnya dikenal sebagai Swagger Specification). Standar gratis dan sumber terbuka ini membuat pengembangan dan dokumentasi API menjadi sangat mudah! Dengan OpenAPI, Anda dapat dengan mudah membuat dan mendokumentasikan API menggunakan format standar yang mudah dipahami.
Hemat waktu Anda untuk mencoba memahami pengembangan dan dokumentasi API yang kompleks. Biarkan kami membantu Anda menyederhanakan prosesnya dengan OpenAPI!
Apa itu OpenAPI Specification (OAS)
OpenAPI adalah spesifikasi yang mendefinisikan struktur dari sebuah RESTful API dan menjelaskan kemampuannya. OpenAPI Specification menyediakan cara standar untuk mendokumentasikan dan berinteraksi dengan API, memungkinkan pengembang untuk menemukan dan memahami cara kerjanya secara efisien. RESTful API menggunakan protokol HTTP untuk transmisi data, sehingga memudahkan platform dan sistem yang ditulis dalam bahasa pemrograman yang berbeda untuk berkomunikasi.
Dengan OpenAPI, Anda tidak memerlukan akses ke kode sumber atau inspeksi lalu lintas jaringan untuk memahami cara kerja API. Definisi API itu sendiri menyediakan semua informasi yang Anda butuhkan.
Format OpenAPI
Versi terbaru dari OpenAPI adalah 3.0. Definisi OpenAPI dapat ditulis dalam JSON atau YAML. JSON merepresentasikan data menggunakan pasangan kunci-nilai daripada menulis deskripsi API yang panjang dan mengikuti struktur OpenAPI. Hal ini memudahkan untuk memahami kemampuan API, bahkan jika Anda tidak memiliki akses ke kode sumber atau dokumentasi.
Contoh spesifikasi OpenAPI 3.0 dalam Format JSON:
{
"openapi": "3.0.0",
"info": {
"title": "Judul API",
"description": "Deskripsi API",
"version": "1.0.0"
}
}
}
Sebagai contoh, Dalam dokumentasi tradisional, Anda akan menulis bagian terpisah untuk setiap metode API, menjelaskan apa yang dilakukannya dan cara menggunakannya. OpenAPI mengambil pendekatan yang berbeda dengan mengatur informasi ini ke dalam serangkaian pasangan kunci-nilai. Setiap metode memiliki serangkaian properti yang mendeskripsikannya, termasuk parameter permintaan dan kode respons.
Meskipun JSON adalah format standar untuk OpenAPI, Anda juga dapat menggunakan YAML, bahasa markup yang lebih sederhana. Hal ini membuatnya lebih mudah untuk membuat dan mengedit dokumen OpenAPI.
openapi: 3.0.0
info:
title: Judul API
description: Deskripsi API
version: 1.0.0
Jadi, begitulah dasar-dasar dari OpenAPI. Mungkin tampak sedikit teknis pada awalnya, tetapi begitu Anda menguasainya, Anda akan bertanya-tanya bagaimana Anda bisa hidup tanpanya.
Spesifikasi OpenAPI menggunakan tipe data JSON yang didefinisikan dalam JSON Schema Specification. Tipe data ini mencakup integer, angka, boolean, dan string. Anda juga dapat memodifikasi format tipe data ini menggunakan properti 'format', seperti int32, int64, float, double, binary, data, date-time, dan format password. OpenAPI juga memungkinkan penggunaan model (objek) yang didefinisikan di bawah spesifikasi JSON sebagai objek skema.
Struktur OpenAPI
Spesifikasi OpenAPI adalah dokumen yang menjelaskan struktur dan perilaku REST API. Mari kita selami lebih dalam dokumen OpenAPI.
Dokumen OpenAPI memiliki format terstruktur yang terdiri dari objek atau array objek yang mengelompokkan pasangan kunci-nilai terkait. Set kurung kurawal pertama {} dalam dokumen OpenAPI berisi semua properti dan disebut "objek dokumen". Meskipun ada beberapa fleksibilitas, dokumen OpenAPI harus mematuhi struktur dasar. Beberapa bagian tingkat tinggi bersifat wajib, sementara yang lain bersifat opsional, memungkinkan variasi dalam spesifikasi OpenAPI di berbagai API.
Dokumen OpenAPI dapat berisi bagian-bagian berikut:
- OpenAPI: API memerlukan spesifikasi versi OpenAPI untuk memungkinkan alat mengurai spesifikasi OpenAPI dan menghasilkan dokumentasi.
- Info: Bidang ini berisi metadata tentang API, seperti judul, deskripsi, dan versinya. Berbagai alat dapat memanfaatkan informasi ini.
- Server: Bidang ini dalam OpenAPI Specification terdiri dari array objek server, yang masing-masing berisi URL untuk host server dan deskripsi singkat tentang server. Informasi ini memberikan detail koneksi yang dapat Anda gunakan untuk berinteraksi dengan server.
- Paths: Objek ini berisi jalur relatif ke titik akhir terpisah dari API. Setiap jalur mencakup operasi yang tersedia untuk berinteraksi dengan API, seperti POST, GET, PUT, atau DELETE.
- Components: Bidang ini dalam OpenAPI Specification adalah objek yang berisi skema yang dapat digunakan kembali untuk badan permintaan, skema respons, dan skema keamanan. Skema ini dapat direferensikan di seluruh spesifikasi menggunakan tag $ref, terutama dalam objek path.
- Security: Objek yang mendeklarasikan jenis skema keamanan yang mengotorisasi permintaan. Objek keamanan didefinisikan secara global atau ditimpa oleh operasi individual.
- Tags: Objek yang berisi metadata yang menentukan urutan di mana Anda harus menampilkan sumber daya API dalam dokumentasi.
- ExternalDocs: Objek yang menautkan ke dokumentasi tambahan, seperti panduan pengguna.
Berikut adalah templat dasar untuk dokumen OpenAPI dengan bidang yang diperlukan dalam format YAMLJSON.
Permintaan POST
Contoh titik akhir berikut untuk permintaan POST untuk mengunggah gambar hewan peliharaan didefinisikan.
openapi: 3.0.3
info:
title: Swagger Petstore - OpenAPI 3.0
version: 1.0.11
servers:
- url: https://petstore3.swagger.io/api/v3
tags:
- name: pet
description: Everything about your Pets
paths:
/pet/{petId}/uploadImage:
post:
tags:
- pet
summary: mengunggah gambar
description: ''
operationId: uploadFile
parameters:
- name: petId
in: path
description: ID hewan peliharaan yang akan diperbarui
required: true
schema:
type: integer
format: int64
- name: additionalMetadata
in: query
description: Metadata Tambahan
required: false
schema:
type: string
requestBody:
content:
application/octet-stream:
schema:
type: string
format: binary
responses:
'200':
description: operasi berhasil
Anda dapat menjalankan cuplikan kode di atas di https://editor.swagger.io/. Berikut ini akan menjadi outputnya.
Cuplikan kode dimulai dengan memberikan informasi dasar tentang API, seperti judul dan versinya. Ia juga menentukan URL dasar untuk server API.
Bagian tags mendefinisikan tag yang disebut "pet" yang mengelompokkan semua titik akhir yang terkait dengan hewan peliharaan. Bagian paths berisi definisi untuk titik akhir /pet/{petId}/uploadImage.
Titik akhir /pet/{petId}/uploadImage mendukung metode POST untuk mengunggah gambar untuk hewan peliharaan. Bagian parameters mendefinisikan dua parameter, "petId" dan "additionalMetadata," yang menentukan ID hewan peliharaan yang akan diperbarui dan metadata tambahan untuk gambar yang diunggah.
Bagian request body menentukan struktur badan permintaan, yang diharapkan dalam format biner. Bagian responses mendefinisikan satu kode respons, 200, yang menunjukkan operasi berhasil.
Apa Manfaat dari OpenAPI?
OpenAPI Specification menawarkan beberapa manfaat bagi pengembang yang membangun dan mendokumentasikan API.
OpenAPI Specification menyederhanakan pengembangan API melalui kolaborasi yang lebih baik, konsistensi, pembuatan kode, validasi, dan perkakas. Cara standar dan transparan untuk menjelaskan API menyederhanakan kemampuan tim untuk bekerja sama secara efektif sambil memastikan konsistensi dalam dokumentasi API.
Pengembang dapat menghasilkan kode untuk API dalam berbagai bahasa pemrograman, menjaga konsistensi di seluruh bahasa. File dokumentasi yang dihasilkan dapat diandalkan dan konsisten sekaligus menghemat waktu bagi pengembang.
Alat validasi membantu menjamin kompatibilitas dan mencegah kesalahan, sementara ekosistem perkakas yang kaya menyederhanakan seluruh proses pengembangan API. OpenAPI Specification mengurangi kesalahan dan meningkatkan kualitas proyek perangkat lunak yang dihasilkan.
Cara Membuat OpenAPI Specification
Tetapi bagaimana jika Anda lebih suka menghindari penulisan kode secara manual? Jangan khawatir, kami di sini untuk membantu! Apidog adalah alat yang membuat bekerja dengan OpenAPI Specification menjadi mudah. adalah platform berbasis cloud yang menyederhanakan perancangan, pengujian, dan penerbitan API. Dengan ini, pengembang dapat membuat dan mengedit spesifikasi OpenAPI menggunakan editor visual yang intuitif.
Apidog juga menyertakan pengujian bawaan yang memungkinkan pengembang untuk menguji API mereka langsung dari platform. menyediakan pasar API tempat pengembang dapat menemukan dan menggunakan API yang telah dibuat sebelumnya dari pengembang lain. Dengan ini, Anda dapat dengan cepat menambahkan jalur, parameter, dan respons ke API Anda menggunakan antarmuka yang intuitif.
Bagian terbaiknya? Apidog menghasilkan dokumentasi secara otomatis. Hanya dengan beberapa klik, Anda dapat membuat dokumentasi yang indah untuk API Anda berdasarkan spesifikasi OpenAPI-nya. Dokumentasi mencakup informasi tentang setiap titik akhir, termasuk parameter, respons, dan contohnya.
Mari kita lihat panduan langkah demi langkah tentang bagaimana kita dapat melakukannya. Berikut adalah proses langkah demi langkah untuk mengimpor file spesifikasi OpenAPI ke Apidog:
Langkah 1. Buka situs web Apidog
Pertama, buka situs web Apidog di browser web Anda. Anda dapat mengaksesnya dengan mengunjungi situs web mereka.
Langkah 2. Masuk ke Akun Anda
Jika Anda memiliki akun API Dog yang sudah ada, masuk dengan mengklik tombol "Sign In" di sudut kanan atas halaman. Jika Anda tidak memiliki akun, Anda dapat membuatnya dengan mengklik tombol "Sign Up" dan mengikuti instruksi.
Langkah 3. Buat Proyek Baru
Setelah masuk, klik tombol "Create Project" untuk membuat proyek baru.
Langkah 4. Impor File OpenAPI
Impor file spesifikasi OpenAPI pada halaman pembuatan proyek. Klik tombol "Import" untuk melanjutkan.
Langkah 5. Unggah File OpenAPI Anda:
Pada halaman impor, Anda akan melihat bidang tempat Anda dapat memasukkan URL file OpenAPI Anda. Jika Anda tidak memiliki URL, Anda dapat mengunggah file dari mesin lokal Anda dengan mengklik opsi "or upload a file" dan memilih file.
Memasukkan URL File JSON saya.
Langkah 6. Tunggu hingga Impor Selesai
Tergantung pada ukuran dan kompleksitas file OpenAPI Anda, proses impor mungkin memakan waktu beberapa menit.
Apidog akan secara otomatis mengurai file dan menghasilkan API baru di akun Anda.
Langkah 7. Konfigurasikan Pengaturan API Anda
Setelah mengimpor file OpenAPI, Anda akan diarahkan ke halaman pengaturan untuk API baru Anda. Anda dapat mengonfigurasi pengaturan yang berbeda di halaman ini, seperti nama API, deskripsi, dan persyaratan autentikasi.
Langkah 8. Mulai Membangun API Anda
Setelah Anda mengonfigurasi pengaturan API Anda, Anda dapat menambahkan titik akhir dan dokumentasi ke API Anda menggunakan antarmuka intuitif '
Dengan mengikuti langkah-langkah sederhana mengimpor file spesifikasi OpenAPI ke Apidog, Anda dapat mengelola dan mendokumentasikan proyek API Anda dengan lebih efisien. File spesifikasi biasanya menyertakan detail penting seperti titik akhir POST, jalur, parameter, dan kode respons.
Setelah menambahkan file spesifikasi Anda ke Apidog, Anda dapat memanfaatkan API yang mudah digunakan dan alat canggih untuk memastikan konsistensi dan keandalan dalam proses pengembangan API Anda. Jadi, jika Anda ingin menghemat waktu dan menyederhanakan proses pengembangan API Anda, pertimbangkan untuk menggunakan OpenAPI Specification dengan Apidog.
