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:
openapi: 3.0.0
info:
title: Judul API
description: Disini deskripsi terkait API yang kita buat.
version: 0.1.1
servers:
- url: https://api.example.com/v1
description: Deskripsi mengenai Base URL.
- url: https://staging-api.example.com
description: Deskripsi mengenai Base URL.
paths:
/users:
get:
summary: Judul endpoint.
description: Deskripsi endpoint.
responses:
'200': # status code
description: Deskripsi response ketika sukses.
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.
info:
title: Judul API
description: Disini deskripsi terkait API yang kita buat.
version: 0.1.1
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.
servers:
- url: https://api.example.com/v1
description: Live Production
- url: https://staging-api.example.com
description: Staging (Dev)
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).
paths:
/users:
get:
summary: Judul endpoint.
description: Deskripsi endpoint.
responses:
'200': # status code
description: Deskripsi response ketika sukses.
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, berikut caranya:
Menggunakan redoc-cli
Pertama kita install terlebih dahulu redoc-cli menggunakan npm dengan menjalankan perintah dibawah:
npm install -g redoc-cli
Buka terminal lalu arahkan ke direktori yang sama dimana kita save file .yaml tadi. Untuk melihat tampilan maka kita bisa menjalankan perintah dibawah:
redoc-cli serve namafile.yaml
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:
redoc-cli bundle namafile.yaml
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:
<!DOCTYPE html>
<html>
<head>
<title>ReDoc</title>
<!-- needed for adaptive design -->
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
<!--
ReDoc doesn't change outer page styles
-->
<style>
body {
margin: 0;
padding: 0;
}
</style>
</head>
<body>
<redoc spec-url='http://petstore.swagger.io/v2/swagger.json'></redoc>
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
</body>
</html>
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:
