Dokumentasi REST API dengan Swagger + ReDoc, dan publish ke Github Pages
Tahapan membuat GithubPages
- Login ke dalam akun github, kemudian di pojok kanan atas terdapat menu dropdown dan pilih New repository
2. Pastikan repository name diisi dengan format <username>.github.io, description, optional bisa di isi atau tidak sesuai kebutuhan untuk menjelaskan isi repository tersebut
3. Pilih setting visibilitas repository menjadi public untuk membuat Github Pages
4. Pilih inisialisasi repository dengan README
5. Klik Create Repository
Untuk melihat github pages yang sudah dibuat berjalan atau tidak bisa masuk ke menu setting di dalam repository
Kemudian scroll ke kebawah ke bagian Github Pages
nantinya url itu yang akan digunakan untuk mengakses dokumentasi api yang kita buat di Redoc nanti.
Membuat Dokumentasi API dengan Redoc
Untuk membuat api dokumentasi, pertama kita download file json/yaml dari dokumentasi API yang sudah kita buat di swagger. Masuk kedalam project swagger kemudian di pojok kanan atas ada menu dropdown Export, pilih Download API, kemudian Pilih JSON Resolved atau YAML Resolved
Setelah itu clone remote repository yang sudah di buat tadi ke Local repository. Didalam repository klik tombol hijau Code kemudian copy link git tersebut.
Selanjutnya buka Terminal / Command Prompt di windows, masuk ke direktori manapun untuk tempat menaruh project yang akan di clone nanti, pada tahap ini saya akan membuat folder baru di direktori Documents dengan mengetikmkdir <nama folder>.
Kemudian cd <nama folder>untuk masuk kedalam direktori folder yang sudah dibuat
Setelah itu di terminal ketik git clone <link repository yang sudah di copy> kemudian tekan enter
Jika sudah berhasil masuk ke dalam folder project cd <nama repository> , setelah masuk ke dalam folder ketik code . untuk masuk kedalam text editor Visual Studio Code
Didalam text editor create sebuah file dengan nama index.html, kemudian copy text html dibawah ini (sumber html berasal dari Redoc’s “TL;DR” readme instructions on GitHub)
<!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>Kemudian file YAML/JSON yang telah di download di awal dimasukkan ke dalam folder projek.
Pada bagian spec-url bisa di ganti sesuai dengan lokasi file YAML/JSON menjadi
<redoc spec-url='./openapi.yaml'>Save, klik kanan pada Visual Studio kemudian pilih Open with Live Server jika sudah ada ekstensi Live Server
Jika belum ada download ekstensi Live Server
Jika sudah secara otomatis akan di arahkan ke halaman http://127.0.0.1:5500/index.html. Jika berhasil akan muncul dokumentasi API yang kita buat dengan Redoc
untuk edit API yang dibutuhkan untuk kebutuhan dokumentasi anda bisa edit di file openapi.yaml
Push perubahan ke dalam Github Page
Untuk update kedalam github page, file index.html dan openapi.yaml yang kita tambah akan kita masukan ke repository github yang kita buat di awal.
Buka terminal di Visual Studio Code, kemudian ketik git add -- all untuk mengupdate semua perubahan di local repository kita.
Kemudian commit semua perubahan git commit -m "message"
git push -u origin master untuk push semua perubahan kedalam remote respository.
Setelah itu cek kembali url yang ada di menu setting repository, klik url link nya
Jika sudah akan muncul halaman Redoc Documentation
Memuat dokumentasi api lain ke dalam Github Page
Untuk update dokumentasi api projek lain kedalam github page, kita bisa membuat folder baru di dalam folder yang sudah kita buat.
Kemudian copy file index.html dan openapi.yaml yang sudah dibuat kedalam folder baru
Setelah itu ketik git add -- all untuk mengupdate kembali semua perubahan di local repository kita.
Kemudian commit semua perubahan git commit -m "message"
git push -u origin master untuk push semua perubahan kedalam remote respository.
ketik url Github Pages dengan /<namafolder yang di tambahkan>
Jika berhasil muncul root folder dokumentasi baru yang telah di buat di github pages
