Azis Hapidin Backend Developer, sering membuat REST API dan Web-Based Application (Full Stack). Kadang ngoprek-ngoprek server ketika diperlukan.

Membuat Dokumentasi REST API dengan OpenAPI Spec + ReDoc

7 min read


Salah satu hal penting setelah kita membuat sebuah REST API (selanjutnya kita sebut API saja) adalah membuat dokumentasi yang mudah difahami dan enak dibaca. Selain agar orang lain bisa menggunakan API kita dengan mudah tanpa harus bertanya-tanya lagi kepada kita, juga agar developer lain yang ingin melanjutkan pengembangan API kita bisa dengan mudah memahami API yang sudah kita buat sebelum membuka kode.

Ada banyak sekali teknik untuk membuat dokumentasi API. Yang paling klasik mungkin kita pernah menemukan dokumentasi yang diketik secara manual di Word lalu dijadikan PDF, atau kirim langsung URL Postman Collection, dan masih banyak cara lainnya. Salah satu cara yang cukup populer untuk membuat dokumentasi API adalah dengan membuat OpenAPI Specification.

 

Apa itu OpenAPI?

OpenAPI Specification merupakan sebuah standar format untuk men-describe dan juga mendokumentasikan API yang sudah digunakan oleh banyak developer dari seluruh dunia. OpenAPI saat ini dibina oleh OpenAPI Initaitive, OpenAPI dirancang agar bisa dimengerti baik oleh mesin ataupun manusia. Saat tulisan ini dibuat, OpenAPI Specification sudah mencapai versi  3.1.0.

Enaknya membuat dokumentasi dengan OpenAPI ini adalah kita bisa generate menjadi banyak bentuk seperti website atau juga pdf. Dalam kasus kali ini kita akan generate menjadi sebuah website dengan bantuan Redoc, kurang lebih nanti tampilannya akan seperti ini: http://redocly.github.io/redoc/

 

Apa itu ReDoc?

ReDoc adalah sebuah tool open-source untuk membuat sebuah website dokumentasi API dari sebuah OpenAPI Specification, tool ini dibuat oleh perusahaan bernama Redocly.

 

Membuat OpenAPI Document

Oke langkah pertama adalah kita harus membuat sebuah OpenAPI Document terlebih dahulu, untuk mempermudah bagian ini kita akan menggunakan tools Swagger Editor, kita cukup menuliskan kode di kolom sebelah kiri maka hasilnya akan langsung muncul di kolom sebelah kanan.

Oh iya OpenAPI Document sendiri mendukung JSON dan juga YAML, tapi disini kita akan menggunakan YAML agar lebih mudah dibaca dan lebih pendek.

Struktur Dasar

Struktur dasar OpenAPI Document kurang lebih seperti ini:

Untuk memastikan kode diatas berjalan, silahkan copy kode diatas lalu paste pada Swagger Editor tadi, maka hasilnya kurang lebih akan seperti ini:

Meta Data

Metadata berisi informasi umum pada API kita seperti judul, deskripsi, versi kode, dsb. List lebih lengkapnya bisa cek halaman ini.

 

Servers/Base URL

Servers berisi list Base URL pada API yang kita buat, biasanya terdiri dari Live Production dan Staging (Development), bisa kurang atau lebih tergantung kebutuhan.

 

Paths/Endpoint

Paths berisi list endpoint dari API yang kita buat, minimal terdiri dari nama endpoint, path, dan juga Request Body (jika ada). Jika ingin lebih lengkap kita juga bisa menambahkan contoh request dan juga contoh response yang akan diberikan API baik ketika sukses (2xx) ataupun error (3xx, 4xx, 5xx).

 

Contoh-contoh diatas hanya pembahasan sekilas saja. Untuk lebih lengkapnya terkait syntax OpenAPI Document temen-temen bisa cek di dokumentasi yang disediakan oleh Swagger dan Open API Initiative disini dan juga disini.

 

Generate Web Dokumentasi dengan ReDoc

Karena dari tadi kita hanya ngetik di Swagger Editor, maka kita coba save kode yang tadi sudah kita buat dengan ekstensi .yaml.

Ada beberapa cara yang bisa kita gunakan untuk menggunakan Redoc, tapi disini kita akan bahas 2 cara saja, pertama menggunakan redoc-cli dan yang kedua adalah memanggil ReDoc Script ke HTML:

Menggunakan redoc-cli

Pertama kita install terlebih dahulu redoc-cli menggunakan npm dengan menjalankan perintah dibawah:

Buka terminal lalu arahkan ke direktori yang sama dimana kita save file (yang .yaml) tadi. Untuk melihat tampilan maka kita bisa menjalankan perintah dibawah:

Lalu terminal akan menunjukan url untuk mengakses dokumentasi API yang kita buat:

Jika dirasa sudah oke, maka kita bisa build menjadi file HTML dengan perintah dibawah:

Maka redoc-cli akan mem-build menjadi 1 static html bernama redoc-static.html yang berisi dokumentasi API kita.

Lebih lengkapnya terkait redoc-cli bisa cek di halaman ini: https://github.com/Redocly/redoc/blob/master/cli/README.md

Memanggil Redoc Script pada HTML

Jika males install lewat npm dan males buka terminal, maka kita bisa menggunakan cara satu ini yaitu dengan membuat sebuah file html dengan isi kurang lebih seperti ini:

Silahkan ganti http://petstore.swagger.io/v2/swagger.json dengan path OpenAPI Document yang sudah kita buat sebelumnya. Dan tadaaa.. dokumentasi API sudah jadi.


Konten di artikel ini hanya pembahasan sekilas saja, jika ingin lebih lengkap silahkan buka dokumentasi resmi OpenAPI.

Sekian, terima kasih atas kunjungannya.

Referensi:

  • https://en.wikipedia.org/wiki/OpenAPI_Specification
  • https://github.com/Redocly/redoc/blob/master/cli/README.md

Azis Hapidin Backend Developer, sering membuat REST API dan Web-Based Application (Full Stack). Kadang ngoprek-ngoprek server ketika diperlukan.