Koleksi Postman Bukan Sumber Kebenaran: Mengapa dan Cara Mengatasinya

Pertanyaan postman collections vs openapi spec muncul setiap kali sebuah tim berkembang melebihi segelintir insinyur. Anda membuka koleksi yang Anda tulis enam bulan lalu dan menemukan bahwa koleksi tersebut menjelaskan sebuah endpoint yang sekarang memiliki tiga bidang wajib tambahan, dua parameter yang usang, dan bentuk respons yang tidak lagi cocok dengan apa yang sebenarnya dikembalikan oleh server. Spesifikasi OpenAPI di Git mengatakan sesuatu yang berbeda. Swagger UI Anda mengatakan sesuatu yang lain. Tidak ada yang yakin mana yang benar.

Penyimpangan itu bukanlah kegagalan alat. Itu adalah kegagalan alur kerja, dan perbedaannya penting. Postman adalah alat yang sangat baik untuk eksekusi permintaan, pembuatan skrip, dan pengujian eksplorasi. Masalahnya adalah ketika tim memperlakukan koleksi sebagai kontrak API itu sendiri, bukan sebagai artefak yang berasal dari kontrak tersebut.

tombol

Mengapa koleksi bergeser sejak awal

Koleksi Postman adalah artefak yang mengutamakan permintaan. Anda mengirimkan permintaan, mengamati respons, dan menyimpannya. Seiring waktu, Anda menambahkan skrip pra-permintaan, substitusi variabel, asersi pengujian, dan struktur folder yang mencerminkan cara tim Anda berpikir tentang API, tidak selalu apa yang secara formal dispesifikasikan oleh API.

Spesifikasi OpenAPI Anda, sebaliknya, adalah artefak yang mengutamakan kontrak. Ini mendeklarasikan jalur, parameter, skema, dan tipe respons dalam format yang dapat dibaca mesin sehingga alat dapat memvalidasi, meniru, dan menghasilkan kode darinya.

Kedua artefak tersebut menjawab pertanyaan yang berbeda. Koleksi menjawab "bagaimana cara saya memanggil endpoint ini hari ini?" Spesifikasi menjawab "apa yang seharusnya dilakukan API ini?" Ketika tim memelihara keduanya secara independen, mereka pasti akan menyimpang. Satu pengembang memperbarui spesifikasi saat menggabungkan permintaan tarik. Yang lain memperbarui koleksi ketika mereka menyadari sebuah pengujian rusak. Tidak ada yang menggabungkannya. Dalam beberapa bulan Anda memiliki dua deskripsi API yang sama yang sebagian akurat, dan tidak ada cara yang dapat diandalkan untuk mengetahui mana yang lebih terkini.

Bukti pelanggan untuk pola ini konkret. Inventis Korea melaporkan masalah persis ini: tim mereka membangun API, menghasilkan spesifikasi OpenAPI untuk Swagger, mengimpor koleksi ke Postman untuk pengujian, dan kemudian menghabiskan upaya berkelanjutan untuk menjaga tiga representasi tetap sinkron. Pengujian melewatkan kasus-kasus ekstrem karena koleksi tidak mencerminkan skema penuh. Dokumentasi bergeser karena spesifikasi bukanlah masukan untuk pembuatan pengujian. Ini bukan kasus-kasus ekstrem; ini adalah hasil yang dapat diprediksi dari alur kerja yang mengutamakan permintaan dalam skala besar.

Akar penyebab: Postman tidak dirancang untuk menjadi penyimpanan spesifikasi

Koleksi Postman memiliki formatnya sendiri. Skema koleksi Postman adalah struktur JSON proprietary yang menggambarkan permintaan, skrip, dan hierarki folder. Ini bukan OpenAPI. Postman dapat mengimpor dan mengekspor OpenAPI, tetapi konversinya bersifat lossy di kedua arah: OpenAPI-ke-koleksi menghilangkan detail skema yang tidak dapat diekspresikan sebagai permintaan; koleksi-ke-OpenAPI menghilangkan skrip dan data yang tidak dapat diekspresikan sebagai bidang spesifikasi.

Ini bukan kritik terhadap Postman. Ini adalah deskripsi tentang kegunaan sebenarnya dari alat tersebut. Postman adalah request runner dengan fitur kolaborasi yang dibangun di sekitar model yang berpusat pada permintaan. Menggunakannya sebagai deskripsi API kanonis Anda mengharuskan Anda untuk memaksakan struktur yang tidak dirancang untuk dibawa oleh format tersebut.

Bandingkan dua representasi untuk satu endpoint:

Tabel tersebut menunjukkan mengapa penyimpangan terjadi: koleksi tidak dapat sepenuhnya mengekspresikan kontrak, sehingga kontrak berada di tempat lain, dan keduanya menjadi tidak sinkron segera setelah seseorang mengedit salah satu tanpa yang lain.

Apa arti sebenarnya dari "spec-first" untuk tim Postman

Pendekatan "spec-first" tidak berarti "merancang semuanya di YAML sebelum menulis kode apa pun." Bagi sebagian besar tim yang bermigrasi dari alur kerja yang berpusat pada koleksi, ini berarti membalikkan dependensi. Metodologi spec-first menempatkan dokumen OpenAPI di Git sebagai deskripsi API yang otoritatif. Setiap artefak lain, termasuk koleksi yang Anda gunakan untuk pengujian, berasal dari dokumen itu, bukan sebaliknya.

Dalam praktiknya, alur kerja terlihat seperti ini:

1. Spesifikasi dikomit ke Git dan ditinjau sebagai bagian dari proses PR.
2. Pengujian, mock, dan dokumentasi dihasilkan dari spesifikasi.
3. Ketika API berubah, spesifikasi berubah terlebih dahulu. Artefak hilir diperbarui secara otomatis atau melalui alat.
4. Koleksi yang digunakan tim Anda untuk pengujian eksplorasi dihasilkan dari spesifikasi, sehingga selalu mencerminkan kontrak saat ini.

Koleksi masih ada. Skrip Anda, pengujian berbasis data, dan variabel lingkungan masih ada. Perbedaannya adalah bahwa koleksi berada di hilir spesifikasi, bukan di hulu. Ketika bidang baru muncul di spesifikasi, bidang itu muncul di koleksi yang dihasilkan. Ketika bidang dihapus dari spesifikasi, pengujian gagal karena permintaan yang dihasilkan tidak lagi menyertakannya. Penyimpangan menjadi kegagalan CI, bukan penemuan enam bulan kemudian.

Cara menghasilkan koleksi dari spesifikasi Anda

Ada beberapa cara untuk memperoleh koleksi yang kompatibel dengan Postman dari spesifikasi OpenAPI. Berikut adalah salah satu yang berfungsi dengan Redocly CLI:

# Install Redocly CLI
npm install -g @redocly/cli

# Validate the spec first
redocly lint openapi/petstore.yaml

# Bundle the spec (resolve $ref chains)
redocly bundle openapi/petstore.yaml -o dist/petstore-bundled.yaml

# Convert to Postman collection v2.1 using the openapi-to-postmanv2 library
npm install -g openapi-to-postmanv2

openapi2postmanv2 \
  --spec dist/petstore-bundled.yaml \
  --output dist/petstore-collection.json \
  --prettyPrint

Outputnya adalah JSON koleksi Postman standar. Anda mengimpornya ke Postman atau menggunakannya sebagai koleksi dasar di Newman atau Postman CLI. Skrip pra-permintaan dan variabel lingkungan Anda tetap merupakan file terpisah yang Anda pelihara secara independen; file-file tersebut tidak ditimpa ketika Anda membuat ulang koleksi dari spesifikasi yang diperbarui.

Anda dapat menghubungkan ini ke CI sehingga koleksi selalu dibuat ulang dari spesifikasi sebelum pengujian dijalankan:

# .github/workflows/api-tests.yml
name: API contract tests

on:
  push:
    paths:
      - "openapi/**"
      - "src/**"

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install dependencies
        run: |
          npm install -g @redocly/cli openapi-to-postmanv2 newman

      - name: Validate OpenAPI spec
        run: redocly lint openapi/petstore.yaml

      - name: Generate collection from spec
        run: |
          redocly bundle openapi/petstore.yaml -o dist/petstore-bundled.yaml
          openapi2postmanv2 \
            --spec dist/petstore-bundled.yaml \
            --output dist/petstore-collection.json

      - name: Run tests against generated collection
        run: |
          newman run dist/petstore-collection.json \
            --environment config/env-staging.json \
            --reporters cli,junit \
            --reporter-junit-export results/test-results.xml

      - name: Upload test results
        uses: actions/upload-artifact@v4
        with:
          name: test-results
          path: results/

Dengan pola ini, spesifikasi adalah masukan untuk setiap eksekusi pengujian. Perubahan spesifikasi yang merusak pengujian akan terdeteksi pada PR yang sama yang mengubah spesifikasi.

Di mana Apidog cocok dalam alur kerja ini

Nilai Apidog bukanlah karena ia menggantikan Postman sebagai request runner. Nilainya adalah ia menghubungkan spesifikasi OpenAPI ke setiap artefak lain yang digunakan tim Anda, tanpa langkah konversi manual. Spesifikasi di Git tetap menjadi sumber kebenaran; Apidog adalah lapisan kolaborasi dan eksekusi di atasnya.

Mode Spec-First Apidog (saat ini dalam versi beta) memungkinkan Anda menyinkronkan spesifikasi OpenAPI dari repositori Git langsung ke ruang kerja Apidog. Dari spesifikasi yang disinkronkan itu, Anda mendapatkan mock yang dibuat secara otomatis, dokumentasi interaktif, dan skenario pengujian, semuanya diperbarui secara otomatis ketika spesifikasi berubah di Git. Anda tidak memelihara koleksi terpisah di samping spesifikasi; spesifikasi mendorong apa yang ditampilkan dan dieksekusi oleh Apidog.

Ini penting bagi tim yang mengalami apa yang dijelaskan oleh STC Group dan World Economic Forum: memelihara Postman untuk pengujian, alat dokumentasi terpisah untuk rendering spesifikasi, dan server mock untuk pengembangan frontend, tiga sistem yang semuanya perlu mencerminkan kontrak API yang sama. Ketika spesifikasi berubah, Anda memperbaruinya di satu tempat dan ketiga permukaan tersebut diperbarui. Penting untuk memverifikasi dalam uji coba apakah izin ruang kerja Apidog dan granularitas SSO memenuhi persyaratan kontrol akses spesifik Anda, terutama untuk tim besar seperti deployment DHL yang dijelaskan (lebih dari 100 pengguna). Itu adalah pertanyaan evaluasi yang berarti untuk bukti konsep.

Untuk jalur migrasi, Anda dapat mengonversi koleksi Postman yang ada ke Apidog sebagai titik awal, kemudian menjadikan spesifikasi sebagai dokumen kanonis ke depannya. Langkah impor mekanis dibahas secara rinci dalam panduan yang ditautkan itu.

Memperlakukan spesifikasi sebagai kode dalam alur kerja Git Anda

Pendekatan api-spec-as-code berarti dokumen OpenAPI mendapatkan perlakuan yang sama dengan kode aplikasi: pull request, tinjauan kode, linting di CI, dan tag versi pada batas rilis. Sebagian besar tim menemukan bahwa mereka sudah memiliki infrastruktur untuk ini; langkah yang hilang adalah menerapkannya ke file spesifikasi.

• Simpan spesifikasi di repositori yang sama dengan layanan yang dijelaskannya, bukan di repositori "docs" terpisah. Ini memastikan perubahan spesifikasi terjadi pada PR yang sama dengan perubahan kode.
• Tambahkan langkah lint Spectral ke pipeline CI Anda. Spectral memvalidasi spesifikasi terhadap spesifikasi OpenAPI dan aturan kustom apa pun yang ditentukan tim Anda. Referensi skema yang rusak, deskripsi yang hilang, dan penamaan yang tidak konsisten menjadi kegagalan CI, bukan komentar tinjauan.
• Gunakan pengembangan spesifikasi berbasis cabang untuk perubahan yang merusak (breaking changes), sama seperti Anda membuat cabang kode aplikasi. Ruang kerja Apidog mendukung percabangan pada spesifikasi, sehingga tim yang berbeda dapat bekerja melawan cabang yang stabil sementara perubahan yang merusak sedang ditinjau.
• Sematkan versi spesifikasi di repositori konsumen hilir. Ketika layanan B bergantung pada spesifikasi layanan A untuk pengujian kontrak, ia harus mereferensikan tag versi tertentu, bukan HEAD dari main.

Pendekatan ini dibahas secara mendalam dalam panduan alur kerja API git-native jika Anda menginginkan pengaturan langkah demi langkah untuk proyek baru.

FAQ

Apakah saya harus berhenti menggunakan Postman sepenuhnya?

Tidak. Perubahan metodologi adalah tentang arah dependensi, bukan penggantian alat. Anda dapat terus menggunakan Postman untuk pengujian eksplorasi dan pembuatan skrip. Perbedaannya adalah koleksi Anda dihasilkan dari spesifikasi sebelum setiap eksekusi pengujian, daripada dipelihara sebagai artefak terpisah. Jika tim Anda lebih memilih UI Postman untuk pekerjaan eksplorasi, preferensi itu kompatibel dengan alur kerja yang mengutamakan spesifikasi.

Apa yang terjadi pada skrip Postman dan variabel lingkungan yang sudah ada?

Skrip pra-permintaan, skrip pengujian, dan definisi variabel lingkungan Anda bukan bagian dari koleksi yang dihasilkan. Itu adalah file terpisah yang Anda pelihara secara independen. Ketika Anda membuat ulang koleksi dari spesifikasi yang diperbarui, skrip tidak akan ditimpa. Anda mempertahankan lapisan perilaku (skrip) sementara lapisan struktural (definisi permintaan) selalu berasal dari spesifikasi.

Bagaimana cara menangani endpoint yang belum ada dalam spesifikasi?

Dalam alur kerja yang mengutamakan spesifikasi, endpoint yang tidak ada dalam spesifikasi belum siap untuk diuji. Kedengarannya ketat, tetapi itulah intinya: gerbang spesifikasi memastikan bahwa endpoint baru dijelaskan secara formal sebelum pengujian ditulis untuknya. Untuk pengembangan eksplorasi, Anda dapat bekerja dengan stub lokal dan menambahkan entri spesifikasi sebagai bagian dari PR yang memperkenalkan endpoint tersebut. Lihat panduan alat validator OpenAPI terbaik untuk alat yang membuat langkah pengeditan yang mengutamakan spesifikasi lebih cepat.

Apakah Mode Spec-First Apidog tersedia sekarang?

Mode Spec-First Apidog saat ini dalam versi beta. Anda dapat mengaksesnya melalui Apidog dan mengevaluasi apakah alur kerja sinkronisasi Git, dukungan cabang, dan mock yang dibuat secara otomatis memenuhi persyaratan tim Anda. Seperti halnya fitur beta lainnya, ada baiknya diuji terhadap struktur spesifikasi spesifik Anda sebelum berkomitmen padanya sebagai alur kerja produksi.

Apa perbedaan antara ini dan mengimpor spesifikasi saya ke Postman?

Postman dapat mengimpor spesifikasi OpenAPI dan menghasilkan koleksi darinya. Itu adalah konversi satu kali. Koleksi kemudian dipelihara secara independen dari spesifikasi, sehingga penyimpangan segera berlanjut. Alur kerja yang mengutamakan spesifikasi menghasilkan ulang koleksi dari spesifikasi pada setiap eksekusi CI (atau sinkronisasi), sehingga koleksi tidak pernah lebih dari satu build yang ketinggalan dari spesifikasi.

Kesimpulan

Masalah penyimpangan yang dihadapi tim Anda bukanlah bug di Postman. Ini adalah hasil yang dapat diprediksi dari pemeliharaan dua deskripsi API yang sebagian tumpang tindih tanpa dependensi yang jelas di antara keduanya. Solusinya adalah menetapkan spesifikasi OpenAPI di Git sebagai sumber otoritatif, dan memperlakukan koleksi Postman sebagai artefak yang dihasilkan di hilir dari spesifikasi tersebut.

Pembalikan itu mengubah apa yang rusak dan kapan. Perubahan spesifikasi yang merusak pengujian terdeteksi dalam PR yang membuatnya. Dokumentasi, mock, dan skenario pengujian tetap selaras karena semuanya membaca dari sumber yang sama. Beban pemeliharaan untuk menjaga dua sistem tetap sinkron hilang karena hanya ada satu sistem.

Unduh Apidog dan buka ruang kerja Mode Spec-First dengan spesifikasi OpenAPI Anda yang sudah ada. Jika Anda memulai dari koleksi daripada spesifikasi, Anda dapat mengimpor koleksi sebagai titik awal OpenAPI dan kemudian bekerja maju dengan spesifikasi dari sana. Alur kerja sinkronisasi Git menjadi nyata setelah Anda melihatnya berjalan terhadap API Anda sendiri, daripada contoh yang dibuat-buat.

tombol