API Documentation (OpenAPI) — API

Dokumentasi API yang baik adalah kunci agar developer lain (dan kamu sendiri di masa depan) bisa menggunakan API dengan mudah. OpenAPI Specification (dulunya…

Dokumentasi API adalah buku petunjuk untuk developer lain (dan kamu sendiri enam bulan lagi): endpoint apa saja yang ada, apa yang dikirim, apa yang kembali, dan apa yang bisa salah. Bayangin buku menu restoran. Menu yang baik menulis nama masakan, pilihan level pedas, isi porsinya, fotonya, dan catatan "kalau habis, diganti nasi goreng". Kamu bisa memesan tanpa memanggil pelayan untuk bertanya satu per satu. Di API, nama masakan itu endpoint, pilihan level itu parameter, isi porsi itu response, foto itu contoh, dan catatan "kalau habis" itu daftar error.

🧪 Tebakan cepat: schema Book di dokumentasi Toko Buku punya properties id, title, author_id, price, dan stock, tapi tanpa required. Server mengirim buku tanpa stock. Pemeriksa dokumentasi bilang response itu sah atau melanggar? Tebak dulu, jawabannya ada di bagian "Schema: bentuk datanya".

OpenAPI: satu file, dibaca manusia dan mesin

OpenAPI Specification (dulu bernama Swagger) adalah standar industri untuk menulis dokumentasi REST API dalam satu file YAML atau JSON. Pelajaran ini memakai versi 3.1; versi 3.0 juga masih banyak dipakai, dan untuk spec sesederhana ini tulisannya sama. Karena formatnya baku, satu file bisa dipakai banyak alat:

Swagger UI atau Redoc mengubahnya jadi halaman dokumentasi yang bisa langsung dicoba.
Validator memeriksa request dan response sungguhan terhadap file itu.
Generator membuat kode client dari file itu.

Di Laravel, Scribe atau L5-Swagger bisa membuat file-nya dari kode. Di Node, misalnya swagger-jsdoc.

Spec untuk GET /books

Ini dokumentasi endpoint GET /books Toko Buku, yang bisa difilter dengan ?author_id=2:

openapi: 3.1.0
info:
  title: API Toko Buku
  version: 1.3.0
servers:
  - url: https://api.tokobuku.test
paths:
  /books:
    get:
      summary: Daftar buku, bisa difilter per penulis
      parameters:
        - name: author_id
          in: query
          required: false
          schema:
            type: integer
      responses:
        "200":
          description: Daftar buku
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Book"
        "400":
          description: author_id bukan bilangan bulat
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Kesalahan di server
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
components:
  schemas:
    Book:
      type: object
      required: [id, title, author_id, price, stock]
      properties:
        id:
          type: integer
        title:
          type: string
        author_id:
          type: integer
        price:
          type: integer
        stock:
          type: integer
    Error:
      type: object
      required: [error]
      properties:
        error:
          type: string

YAML menyusun tingkatan lewat indentasi dengan spasi (jangan tab). Tanda - membuka satu butir daftar.
paths → /books → get: satu endpoint, alamat lalu method-nya.
parameters: daftar masukan. - name: author_id dengan in: query artinya nilainya datang di query string (?author_id=2), required: false artinya boleh gak dikirim, schema: type: integer artinya harus bilangan bulat.
responses: satu kunci per status code. Tulis kodenya dengan petik, "200":, supaya YAML membacanya sebagai teks, bukan angka.
content → application/json → schema: bentuk body-nya. Untuk 200: type: array yang items-nya Book.

Latihan memakai bentuk yang sama untuk GET /api/products dengan parameter category bertipe string, response "200" dan "500", dan Product berisi id, name, price.

Schema: bentuk datanya

type: object, array, string, integer (bilangan bulat), number (boleh desimal), boolean.
properties: field apa saja yang boleh ada di object, masing-masing dengan schema-nya.
items: bentuk tiap isi array.
required: field yang wajib ada. Ini yang sering lupa: properties cuma menjelaskan field yang ada, gak mewajibkan apa pun. Jadi tanpa required, buku tanpa stock dianggap sah. Itu jawaban tebakannya.
$ref: "#/components/schemas/Book": menunjuk schema yang ditulis sekali di components/schemas. Book dipakai di banyak endpoint, jadi bentuknya ditulis sekali dan dirujuk. Nilainya diberi petik, karena # di YAML membuka komentar.

Cek dokumentasi dengan response sungguhan

Dokumentasi yang basi lebih buruk dari gak ada dokumentasi: developer mengikuti petunjuk yang salah dengan yakin. Contoh: server versi baru mengirim "price": "89000" (teks), sedangkan dokumentasinya bilang integer. Aplikasi yang menjumlahkan harga malah menyambung teks: "89000" + 1000 jadi "890001000".

Karena spec-nya bisa dibaca mesin, ini bisa dicek otomatis. Contract test mengirim request, lalu mencocokkan response-nya dengan spec:

GET /books?author_id=1 -> 200 | response: body[0].price: harus integer, datang string "89000"
GET /books?author_id=dua -> 400 | request: author_id=dua bukan integer | response: cocok dengan spec

Prinsipnya disebut docs-as-code: file spec disimpan di repo yang sama dengan kode, diubah di pull request yang sama, dan dicek di CI. Jadi dokumentasi harus diperbarui bersama perubahan kode, supaya gak basi (outdated).

Isi dokumentasi yang baik

Contoh request dan response yang bisa langsung disalin, misalnya lewat example:

              example:
                - id: 2
                  title: Bumi Manusia
                  author_id: 2
                  price: 125000
                  stock: 0

Semua error: tiap status dan bentuk body-nya ({"error": "..."}), seperti di pelajaran Error Handling.
Autentikasi: cara mendapat token dan cara mengirimnya (pelajaran Autentikasi). Di OpenAPI:

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

lalu security: [{ bearerAuth: [] }] di endpoint yang butuh login, misalnya POST /books.

Batas: rate limit dan pagination (pelajaran Rate Limiting dan Pagination).
Changelog per versi: apa yang ditambah, diubah, dihapus, misalnya "1.3.0: tambah filter author_id di GET /books". Perubahan yang merusak client butuh versi baru, seperti di pelajaran API Versioning.

⚠️ Jebakan yang sering ketemu

Lupa required. Field yang hilang lolos tanpa ketahuan. Tulis semua field wajib di required.
Cuma mendokumentasikan 200. Client gak tahu 400 dan 500 bisa datang, apalagi bentuk body-nya. Daftar juga error-nya.
Indentasi YAML salah atau pakai tab. in: query yang bergeser satu tingkat jadi milik bagian lain. Pakai spasi yang konsisten.
Spec diubah terpisah dari kode. Lama-lama basi. Ubah di PR yang sama, dan cek dengan contract test.

TL;DR: Dokumentasi API memberi tahu apa yang dikirim, apa yang kembali, dan apa yang bisa salah. Standar industrinya OpenAPI (dulu Swagger), satu file YAML atau JSON yang dibaca manusia (Swagger UI, Redoc) dan mesin (validator, generator). Satu endpoint ditulis di paths: parameters (misalnya - name: author_id, in: query, schema: type: integer) dan responses per status code ("200", "400", "500"), masing-masing dengan schema. Array memakai type: array dan items, object memakai properties, dan field wajib harus ditulis di required. Schema yang dipakai berulang ditulis sekali di components/schemas dan dirujuk dengan $ref. Dokumentasi yang baik punya contoh, semua error, autentikasi, dan changelog, dan diperbarui di PR yang sama dengan kodenya (docs-as-code) supaya gak basi.