OpenAPI Specification
OpenAPI Specification (OAS) adalah standar terbuka untuk mendeskripsikan HTTP API dalam YAML atau JSON. Kontraknya dapat dibaca manusia dan diproses tool tanpa harus melihat implementasi server.
Sering digunakan untuk REST, tetapi OpenAPI tidak mensyaratkan semua batasan arsitektur REST. Spesifikasinya dahulu bernama Swagger; kini Swagger juga merujuk pada ekosistem tool yang bekerja dengan OpenAPI.
Isi kontrak
- Endpoint dan operasi: path serta HTTP method yang tersedia.
- Input dan output: parameter, request body, response, status code, dan schema data.
- Keamanan: skema autentikasi dan persyaratan akses yang dideskripsikan API.
- Metadata: judul, versi API, deskripsi, dan alamat server.
YAML atau JSON adalah format dokumen OpenAPI, bukan pembatas format payload API yang dideskripsikannya.
Kegunaan dan batasan
Tool dapat memakai kontrak untuk menghasilkan dokumentasi interaktif, client SDK, dan bahan pengujian. Kontrak yang sama membantu tim menyepakati desain APIs sebelum implementasi dibuat.
Documentation Generation with AI menempatkan kontrak sebagai dasar dokumentasi, bukan tebakan dari potongan kode. Namun, dokumen OpenAPI tidak otomatis menjamin server mengikuti kontrak atau menerapkan autentikasi dengan benar. Kesesuaian implementasi tetap perlu diuji.