Cara Setup Swagger UI dan Prism Untuk Mocking API dan Mendokumentasikannya Menggunakan Docker Compose — Part 1

Sebagai seorang Backend Developer kegiatan mendokumentasikan daftar endpoint atau spesifikasi teknikal sangatlah diperlukan, tujuannya adalah agar teman-teman seperjuangan seperti Front End Developer dan QA juga dimudahkan pekerjaannya.

Salah satu yang menarik bagi saya adalah ternyata bisa loh kita membuat daftar endpoint yang sudah kita tulis di Swagger file tadi kita host dan menghasilkan data fake dengan menggunakan Stoplight Prism dan tentunya open source, jadi Swagger file yang sudah kita buat tadi walaupun dari sisi Backend belum dikerjakan setidaknya Frontend sudah bisa consume data REST API yang nanti nya akan mengembalikan data random akan tetapi result objectnya identik dengan skema yang sudah kita tentukan di swagger filenya.

Let’s code!

Sebelum kita lanjutkan ngoding, kita harus install dan jalankan dulu nih si Docker nya di local system kalian masing-masing, cara installnya saya tidak akan tulis di sini ya, silahkan lihat di dokumentasinya (Tau google kan ?).

Jika sudah, mari kita buat folder baru dan buat file docker-compose.yaml nya:

# bash
mkdir my-swagger
cd my-swagger
touch docker-compose.yml

Kemudian buka folder my-swagger dengan vscode atau IDE yang kamu suka.

Siapkan File Swagger-nya

Untuk contoh kali ini kita akan menggunakan file swagger yang sudah ada saja dan disediakan oleh Swagger langsung dan simpan di folder docs, jalankan perintah ini untuk download filenya:

# bash
mkdir docs
cd docs
curl https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v2.0/yaml/petstore.yaml --output petstore.yaml

Sekarang struktur direktori kita jadi seperti ini:

# bash
my-swagger
├── docker-compose.yaml
└── docs
    └── petstore.yaml

Edit file docker-compose.yaml nya, dan kita butuh 3 image service yaitu:

• Swagger UI (untuk menampilkan dokumentasi)
• Caddy (untuk reverse proxy)
• Prism (untuk mock data)

# docker-compose.yaml
version: "2.4"
services:
  caddy:
    image: caddy
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
    ports:
      - "3000:80"
    depends_on:
      - petstoreService # <- panggil petstoreService ke sini

  swagger-ui:
    image: swaggerapi/swagger-ui
    ports:
      - "4000:8080"
    volumes:
      - ./docs:/usr/share/nginx/html/docs
    environment:
      URLS: "[
          {name: 'Tempat jualan binatang', url: 'docs/petstore.yaml'},
        ]"

  # prism services to mock
  petstoreSvc:
    image: stoplight/prism:4
    volumes:
      - ./docs/petstore.yaml:/tmp/docs/petstore.yaml
    command: "mock -d -p 4010 --host 0.0.0.0 /tmp/docs/petstore.yaml"

Lalu kita akan membuat Caddyfile untuk menentukan rute si petstore.yaml nya mau di mock ke mana. Buka terminal, dan di dalam folder my-swagger kita buat file Caddyfile nya:

# bash
touch Caddyfile

dan buka di code editor kalian kemudian isi dengan:

# Caddyfile
http://localhost

route /petstore/* {
    uri strip_prefix /petstore
    reverse_proxy petstoreSvc:4010
}

Jika sudah, tinggal kita jalankan perintah docker-compose up -d kemudian jika tidak ada kendala kamu bisa lihat dokumentasi API nya di http://localhost:4000 dan mock nya berada di http://localhost:3000 .

Mari kita test!

Mari kita buka di browser http://localhost:4000 maka hasilnya kurang lebih akan seperti ini:

Dan untuk mock, kita coba hit endpoint GET http://localhost:3000/petstore/pets dengan CURL:

# bash
curl -X 'GET' 'http://localhost:3000/petstore/pets' -H 'accpet: application/json'

Hasilnya kita bisa lihat object untuk id name dan lainnya otomatis digenerate dengan data fake.

link repo untuk tutorial ini bisa lihat di sini

• https://github.com/daemswibowo/my-swagger

Untuk part 2, kita akan belajar setup Basic Auth untuk halaman dokumentasi swagger ui nya agar tidak sembarang orang yang dapat mengakses nya.