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

OpenAPI Specification (dulunya Swagger): Format standar industri untuk mendokumentasikan REST API dalam format YAML/JSON.

openapi: 3.0.0
info:
  title: Toko API
  version: 1.0.0
paths:
  /products:
    get:
      summary: List semua produk
      parameters:
        - name: category
          in: query
          schema:
            type: string
      responses:
        200:
          description: Berhasil
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Product"
components:
  schemas:
    Product:
      type: object
      required: [id, name, price]
      properties:
        id:
          type: integer
        name:
          type: string
        price:
          type: number

Swagger UI: Mengubah spec OpenAPI menjadi halaman dokumentasi interaktif yang bisa langsung di-test.

Auto-generating docs:

• swagger-jsdoc: generate OpenAPI spec dari JSDoc comments di kode
• swagger-autogen: scan route Express dan generate spec otomatis
• Laravel: Scribe atau L5-Swagger

Best Practices Dokumentasi API:

1. Sertakan contoh request dan response untuk setiap endpoint
2. Jelaskan error yang mungkin terjadi dan format error-nya
3. Dokumentasikan autentikasi — cara mendapatkan token, cara menggunakannya
4. Tulis deskripsi yang jelas untuk setiap parameter
5. Sediakan getting started guide untuk developer baru
6. Update dokumentasi bersamaan dengan perubahan kode (docs-as-code)
7. Versioning docs — sediakan dokumentasi per versi API

Tools populer: Swagger UI, Redoc, Postman Docs, ReadMe.io, Stoplight.