Bikin Dokumentasi API SIMRS yang

Bikin Dokumentasi API SIMRS yang "Manusiawi" Buat Vendor Lain

Sobat IT RS pasti pernah ngalamin: vendor eksternal minta akses integrasi ke SIMRS, tapi giliran dikirim file swagger.json, mereka malah balik nanya hal basic—padahal semua udah di docs. Atau tim pengembang sendiri, baru dua minggu nggak nyentuh modul bridging, udah lupa alur endpoint-nya. Dokumentasi API sering jadi momok, apalagi kalau isinya kayak output auto-generate, isinya field nama variabel semua, contoh request/response minim. Padahal, dokumentasi bagus itu bisa nyelametin hidup (dan waktu) banyak orang, dari pengembang sampai vendor alat, bahkan user admin RS.

Artikel ini bahas cara bikin dokumentasi API SIMRS yang bukan cuma "ada", tapi bener-bener bisa dipake vendor lain buat integrasi tanpa drama. Fokus ke swagger & Postman, yang sehari-hari paling sering dipakai. Ada tips, contoh konkret, dan template yang bisa dicomot langsung.

Masalah Klasik Dokumentasi API SIMRS

  • Swagger auto-generate, isinya kering: Hanya nama endpoint, field, kadang deskripsi cuma "ID pasien", tanpa konteks.
  • Enggak ada contoh: Orang luar bingung, format tanggal harus yyyy-mm-dd atau dd-mm-yyyy? Nomor rekam medis pakai leading zero?
  • Field ambigu: "kode_unit", "kode_ruang", "idbagian"—beda endpoint, beda makna.
  • Langkah penggunaan enggak jelas: Harus login dulu atau bisa langsung get data? Token expired dalam berapa menit? Header-nya apa aja?
  • Respons error ngambang: Cuma tulis "400 Bad Request", tanpa detail kenapa salah.

Konsep Dokumentasi API yang "Manusiawi"

  • Contoh nyata: Setiap endpoint harus punya contoh request & response valid, juga contoh error.
  • Konteks jelas: Jelasin field sensitif/ambiguous. Link ke referensi kalau perlu (tabel kode unit, mapping status, dsb).
  • Alur step-by-step: Guideline urutan pemanggilan endpoint. Wajib buat proses multi-step (login, ambil token, get pasien, simpan data lab, dsb).
  • Nggak pelit narasi: Pakai bahasa sehari-hari, kasih catatan atau tips di setiap endpoint, terutama yang rawan error/sering ditanya vendor.
  • OpenAPI/Swagger/Redoc/Stoplight, bukan PDF: Paksa tim backend keluar dari kebiasaan bikin docs di Word/PDF. Swagger UI atau Postman Collection lebih hidup, bisa dicoba langsung.

Template Swagger/OpenAPI Sederhana yang Bisa Dipakai

Swagger/OpenAPI file biasanya auto-generate dari framework (misal, Spring Boot, .NET, Flask, Laravel), tapi deskripsi dan contoh wajib diisi manual supaya manusiawi. Contoh basic buat endpoint Get Data Pasien: 

{
  "openapi": "3.0.1",
  "info": {
    "title": "API SIMRS - Data Pasien",
    "description": "Akses data pasien. Token wajib, nomor RM pakai leading zero 8 digit. Format tanggal yyyy-mm-dd.",
    "version": "1.0.0"
  },
  "paths": {
    "/api/pasien/{no_rm}": {
      "get": {
        "summary": "Ambil data pasien berdasarkan nomor rekam medis",
        "parameters": [
          {
            "name": "no_rm",
            "in": "path",
            "description": "Nomor rekam medis (8 digit, leading zero). Contoh: 00012345",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Sukses. Data pasien ditemukan.",
            "content": {
              "application/json": {
                "example": {
                  "no_rm": "00012345",
                  "nama": "Agus Supriyadi",
                  "tgl_lahir": "1982-03-21",
                  "jenis_kelamin": "L",
                  "alamat": "Jl. Melati No. 2, Bekasi"
                }
              }
            }
          },
          "404": {
            "description": "Pasien tidak ditemukan",
            "content": {
              "application/json": {
                "example": {
                  "error": "not_found",
                  "message": "Nomor rekam medis tidak terdaftar di SIMRS"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  }
}

Catatan penting:

  • Deskripsi field harus jelas. Nomor RM leading zero? Tulis!
  • Example harus ada. Request & response, termasuk error.
  • Security dicantumkan. Contoh di atas pakai JWT bearer token.

Contoh "Manusiawi": Narasi di Setiap Endpoint

Swagger nggak harus robotik. Di bagian description, bisa masukin catatan internal: 

{
  "summary": "Ambil data pasien",
  "description": "Endpoint ini sering error kalau nomor RM salah format (harus 8 digit). Kalau pasien baru masuk hari ini, data bisa delay 1-2 menit sampai sinkron ke DB utama. Catatan: Gunakan token yang didapat dari endpoint /api/token, expired 30 menit.",
  ...
}
  • Kasih notes yang suka bikin vendor atau tim internal kecele.
  • Format description di OpenAPI/Swagger support HTML, jadi bisa cetak tebal/italic, bikin list, dsb.

Checklist Minimal Dokumentasi API "Layak Integrasi"

  • Penjelasan otentikasi: Step login, refresh token, expired time, contoh header Authorization.
  • Format parameter jelas: Nomor RM, tanggal, kode referensi (ruang, dokter, dll). Contoh value nyata.
  • Contoh request & response: Termasuk error kasus umum (wrong format, not found, unauthorized).
  • Penjelasan error code: 400/401/403/404, plus pesan error manusiawi.
  • Link referensi eksternal: Kalau integrasi pakai kode BPJS, ICD, atau Kemenkes—link ke mapping/daftar resmi.
  • Alur integrasi singkat: Step by step, minimal dalam 5-7 langkah, gimana vendor bisa mulai tes sampai sukses.

Contoh Step Login Integrasi SIMRS


1. POST /api/token 
   - Body: user, password
   - Response: token JWT, expired 30 menit
2. GET /api/pasien/{no_rm}
   - Header: Authorization: Bearer {token}
   - Response: data pasien

Sederhana. Tapi kalau ini enggak ada di docs, vendor pasti tanya, "Ini header-nya apa? Token expired? Usernya dapet dari mana?"

Postman Collection: Jangan Lupa Environment & Catatan

Banyak vendor lebih suka Postman Collection karena tinggal import, klik, langsung bisa cobain endpoint asli. Tapi sering kelupaan:

  • Collection nggak ada environment: Jadi harus ganti-ganti URL manual. Bikin Environment dev, staging, prod.
  • Notes kosong: Setiap request bisa dikasih description. Tulis format parameter, contoh error, dsb.
  • Contoh data real: Jangan pakai "string" atau "12345" doang. Masukin data beneran (asal bukan data sensitif pasien hidup).

Sample Postman Collection (Potongan)

{
  "info": {
    "name": "SIMRS API Collection",
    "description": "Kumpulan endpoint utama SIMRS. Token didapat dari login, expired 30 menit. Nomor RM 8 digit.",
    ...
  },
  "item": [
    {
      "name": "Login - Get Token",
      "request": {
        "method": "POST",
        "header": [],
        "body": {
          "mode": "raw",
          "raw": "{\n  \"username\": \"vendor1\",\n  \"password\": \"rahasia123\"\n}"
        },
        "url": {
          "raw": "{{base_url}}/api/token",
          "host": [
            "{{base_url}}"
          ],
          "path": [
            "api",
            "token"
          ]
        },
        "description": "Dapatkan token JWT. User & password didaftarkan oleh admin SIMRS."
      },
      "response": [
        {
          "code": 200,
          "body": "{\n  \"token\": \"eyJhbGciOiJIUzI1...\",\n  \"expired_in\": 1800\n}"
        }
      ]
    },
    ...
  ]
}

Tips: Postman bisa export docs otomatis (View > Docs). Tapi pastikan deskripsi tiap endpoint benar-benar jelas, jangan default kosong.

Studi Kasus: Dokumentasi API Bridging Lab SIMRS

Vendor alat hematologi minta integrasi: ambil order, kirim hasil ke SIMRS. Kalau dokumentasi cuma kasih endpoint /api/lab/order tanpa detail, vendor bakal bolak-balik tanya. Simak contoh dokumentasi hidup yang "manusiawi": 


GET /api/lab/order?status=menunggu
  - Header: Authorization: Bearer {token}
  - Query param: status = 'menunggu' (ambil orderan baru), 'sudah_kirim' (riwayat)
  - Response:
    [
      {
        "id_order": "LAB2300123",
        "tgl_order": "2023-05-02T08:11:00+07:00",
        "no_rm": "00012345",
        "nama": "Agus Supriyadi",
        "jenis_pemeriksaan": "HEMATOLOGI LENGKAP",
        "dokter": "dr. Rini",
        "kode_unit": "HEM", // Lihat mapping kode di /api/lab/unit
        "catatan": "Pemeriksaan ulang"
      }
    ]

POST /api/lab/hasil
  - Body:
    {
      "id_order": "LAB2300123",
      "hb": 13.2,
      "lekosit": 8800,
      "trombosit": 320000,
      "kesimpulan": "Normal"
    }
  - Response:
    {
      "success": true,
      "message": "Hasil berhasil diterima"
    }
  • Catatan: kode_unit harus pakai kode dari SIMRS, lihat endpoint referensi kode unit.
  • Format tanggal ISO, timezone wajib. Contoh: 2023-05-02T08:11:00+07:00
  • Kalau POST /api/lab/hasil kirim id_order yang udah pernah submit, balikin error: 
    
  {
    "success": false,
    "error": "duplicate_order",
    "message": "Hasil untuk order LAB2300123 sudah pernah dikirim"
  }

Quick Tips: Swagger dan Postman yang Gampang Dibaca

  • Semua endpoint kasih contoh sukses & error.
  • Jelaskan edge-case. Contoh: "Order bisa delay jika data pasien baru."
  • Kasih mapping link. Contoh: "kode_unit: lihat endpoint /api/lab/unit"
  • Pakai penamaan konsisten. Kalau pakai "no_rm" di satu tempat, jangan ganti "norm" di endpoint lain.
  • Wrap kode/format data dengan tag di deskripsi Swagger.

Routing Error Handling di Dokumentasi

  • Kasih contoh error nyata. Jangan cuma tulis "error".
  • Error code konsisten. 400: format salah, 404: data tidak ada, 401: token salah/habis, 409: conflict (duplikat).
  • Deskripsi error mudah dipahami vendor. Hindari internal error string yang bikin vendor bengong ("ERR_ORM_NULLREF").

Contoh Format Error Response


{
  "success": false,
  "error": "invalid_format",
  "message": "Field tgl_lahir harus format yyyy-mm-dd"
}

Kalau status code bukan 200, error message wajib jelas. Ini hemat waktu semua pihak.

Checklist Internal Sebelum Rilis Dokumentasi API

  • Tim sendiri bisa pakai docs tanpa nanya-nanya. Uji coba: suruh junior/anak magang integrasi pakai dokumen tanpa tanya ke senior.
  • Revisi setelah ada tanya vendor. Kalau ada pertanyaan sama berulang, tambahin ke docs di bagian notes/tips endpoint.
  • Versioning jelas. Tiap perubahan endpoint/field, increment version & tulis changelog singkat.
  • PDF? Buat terakhir. Docs utama Swagger UI/Postman, PDF buat backup aja.

Template Tabel Referensi di Dokumentasi

Jangan cuma list field. Kasih contoh value, keterangan, dan referensi, misal: 


| Field         | Tipe    | Contoh         | Keterangan                       |
|---------------|---------|----------------|----------------------------------|
| no_rm         | string  | 00012345       | Nomor rekam medis 8 digit        |
| nama          | string  | Agus Supriyadi | Nama pasien                      |
| tgl_lahir     | string  | 1982-03-21     | Format yyyy-mm-dd                |
| jenis_kelamin | string  | L              | L = Laki-laki, P = Perempuan     |
| kode_unit     | string  | HEM            | Kode unit, lihat endpoint referensi|

Bisa masukin tabel ini di deskripsi endpoint (Swagger support markdown, Postman support HTML/table).

Ringkasan: Tips Praktis Biar Dokumentasi API Jadi "Manusiawi"

  • Kasih contoh nyata di setiap endpoint—request, response, error
  • Penjelasan alur step-by-step (auth, request, error)
  • Deskripsi field & value lengkap, jangan cuma nama variabel
  • Map kode referensi ke endpoint referensi, hindari enum/daftar hardcode di docs
  • Edit manual deskripsi auto-generate. Swagger boleh, asal jangan mentah
  • Update docs tiap ada feedback/vendor tanya hal yang sama

Penutup: Dokumentasi API SIMRS, Investasi Waktu yang Bikin Hidup Lebih Tenang

Jangan males nulis docs. Satu jam bikin dokumentasi yang manusiawi, bisa ngirit ratusan jam ngejawab pertanyaan vendor, internal, sampai tim sendiri nanti. Swagger dan Postman bukan cuma buat formalitas akreditasi—ini kunci integrasi lancar ke depannya.

Sobat IT RS punya tips atau template dokumentasi andalan? Share di kolom komentar! Biar ekosistem SIMRS makin sehat, enggak bikin darah tinggi lagi gara-gara dokumentasi ngambang.