Belajar OpenAPI
Kontrak HTTP yang Bisa Dieksekusi

Dari dokumentasi yang cepat basi ke kontrak yang bisa diverifikasi

Bayangkan tim backend, frontend, mobile, QA, dan integrasi pihak ketiga semuanya menebak bentuk API dari sumber yang berbeda. Backend baca kode handler, frontend baca screenshot Postman, QA baca pesan Slack. Itulah kekacauan yang OpenAPI selesaikan.

OpenAPI Specification (OAS) adalah format standar yang language-agnostic untuk mendeskripsikan HTTP API. Dengan satu dokumen, manusia dan mesin bisa memahami endpoint apa saja yang tersedia, parameter dan body yang dibutuhkan, serta bentuk response yang dikembalikan, semuanya tanpa membaca source code atau menyadap traffic. Lihat OpenAPI Specification resmi untuk teks normatifnya.

Bedanya tajam: dokumentasi manusia ditulis untuk dibaca orang, sedangkan spec OpenAPI ditulis untuk dieksekusi tooling. Dari satu file openapi.yaml yang sama, tooling bisa membangkitkan dokumentasi interaktif, client TypeScript, mock server, dan test kontrak di CI. Dokumentasi yang ditulis tangan cepat basi karena ia terpisah dari kebenaran. Spec yang diverifikasi di CI tidak bisa berbohong tanpa ketahuan.

Inilah satu openapi.yaml paling sederhana untuk daftar produk skincare. Baca pelan-pelan, kita bedah strukturnya di section berikutnya.

api/openapi.yamlSalin
openapi: 3.1.1
info:
  title: Skincare Shop API
  version: 1.0.0
paths:
  /v1/products:
    get:
      operationId: listProducts
      summary: Daftar produk skincare
      responses:
        "200":
          description: Daftar produk berhasil diambil
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string
                    priceRupiah:
                      type: integer

Walaupun pendek, file ini sudah berbicara banyak. Ia menyebut versi spec (3.1.1), identitas API (info), satu endpoint (GET /v1/products), nama unik operasi (operationId), dan bentuk response sukses (array produk dengan id, name, priceRupiah). Frontend bisa langsung tahu apa yang akan diterima, jauh sebelum handler Go pertama ditulis.

Peta besar dari atas ke bawah, plus YAML vs JSON

Sebelum mengisi detail, kunci dulu peta besarnya. Dokumen OpenAPI punya beberapa field top-level yang selalu sama, dan memahami fungsinya membuat sisanya terasa mudah.

Sebuah dokumen OpenAPI 3.1 dibaca dari atas ke bawah dengan urutan logis: deklarasi versi, identitas, lokasi server, daftar endpoint, kumpulan komponen yang dipakai ulang, dan kebijakan keamanan global. Begitu kamu hafal kerangka ini, file sepanjang ribuan baris pun tetap bisa kamu navigasi.

flowchart TD
  Root["Dokumen OpenAPI 3.1.1"] --> V["openapi: versi spec"]
  Root --> Info["info: identitas API"]
  Root --> Servers["servers: base URL per environment"]
  Root --> Paths["paths: daftar endpoint"]
  Root --> Comp["components: schema, parameter, response reusable"]
  Root --> Sec["security: kebijakan auth global"]
  Paths --> Op["operation: get / post / put / patch / delete"]
  Op --> Params["parameters"]
  Op --> Body["requestBody"]
  Op --> Resp["responses"]

Gambar 1. Peta top-level dokumen OpenAPI. paths adalah jantungnya, components adalah lemari penyimpanan bersama.

Spec yang sama bisa ditulis dalam YAML atau JSON. Keduanya setara, hanya beda format penulisan. YAML jauh lebih nyaman dibaca manusia karena ringkas dan mendukung komentar, sedangkan JSON lebih cocok saat dihasilkan atau dikonsumsi mesin. Course ini memakai YAML untuk contoh yang dibaca manusia.

Potongan yang sama persis, ditulis dalam dua format. Perhatikan bahwa YAML memakai indentasi dua spasi sedangkan JSON memakai kurung eksplisit.

contoh.yaml (YAML)Salin
info:
  title: Skincare Shop API
  version: 1.0.0

contoh.json (JSON)Salin
{
  "info": {
    "title": "Skincare Shop API",
    "version": "1.0.0"
  }
}

Inilah skeleton minimal openapi.yaml untuk Skincare Shop API yang akan kita isi sepanjang course. Semua field top-level ada, isinya masih kosong, siap diisi bertahap.

api/openapi.yaml (skeleton)Salin
openapi: 3.1.1
info:
  title: Skincare Shop API
  version: 1.0.0
  description: Kontrak HTTP untuk backend online shop skincare.
servers: []
paths: {}
components:
  schemas: {}
  parameters: {}
  responses: {}
  securitySchemes: {}

Identitas kontrak dan tempat ia berjalan

Object info memberi API sebuah identitas, dan servers menjelaskan di mana API itu bisa dihubungi. Keduanya beda peran: info adalah tentang kontrak, servers adalah tentang deployment.

Mulai dari info. Ia berisi metadata yang membuat spec terasa seperti produk, bukan file mentah: judul, versi, deskripsi, kontak, dan lisensi. Field version di sini adalah versi kontrak API, bukan versi paket atau versi spec OpenAPI. Pakai semantic versioning agar perubahan kontrak punya makna yang jelas.

api/openapi.yaml (info)Salin
info:
  title: Skincare Shop API
  version: 1.0.0
  description: |
    Kontrak HTTP untuk backend online shop skincare.
    Mencakup katalog, cart, checkout, order, auth, dan admin.
  contact:
    name: Tim Backend Skincare
    email: backend@skincare.example
  license:
    name: Proprietary

Sekarang servers. Ia adalah daftar base URL tempat API berjalan. Satu kontrak yang sama biasanya berjalan di banyak environment: laptop developer, staging untuk QA, dan production untuk user nyata. Mencatat semuanya membuat client tahu ke mana harus menembak tanpa menebak.

api/openapi.yaml (servers)Salin
servers:
  - url: http://localhost:8080
    description: Local development
  - url: https://staging-api.skincare.example
    description: Staging untuk QA
  - url: https://api.skincare.example
    description: Production

Untuk URL yang sebagian dinamis, OpenAPI menyediakan server variables. Misalnya base URL yang berbeda hanya pada subdomain region. Variable diberi nilai default dan, bila perlu, daftar enum nilai yang sah.

api/openapi.yaml (server variables)Salin
servers:
  - url: https://{region}.api.skincare.example
    description: Production per region
    variables:
      region:
        default: id
        enum:
          - id
          - sg
        description: Kode region deployment

Jantung OpenAPI dan semantik HTTP method

paths adalah bagian terpenting dokumen. Di sinilah endpoint nyata dideklarasikan: kombinasi path, HTTP method, dan apa yang terjadi saat keduanya dipanggil.

Setiap entri di bawah paths adalah sebuah path item, misalnya /v1/products. Di dalamnya ada satu atau lebih operation object, satu per HTTP method (get, post, put, patch, delete). Tiap operation punya summary, description, tags, dan yang penting operationId: nama unik yang dipakai tooling dan codegen sebagai identitas operasi.

flowchart TD
  Paths["paths"] --> P1["/v1/products"]
  Paths --> P2["/v1/products/{productId}"]
  P1 --> G1["get: listProducts"]
  P1 --> C1["post: createProduct"]
  P2 --> G2["get: getProduct"]
  P2 --> U2["patch: updateProduct"]
  P2 --> D2["delete: deleteProduct"]

Gambar 2. Satu path item bisa punya banyak operation, satu per method. Tiap operation punya operationId unik.

api/openapi.yaml (paths)Salin
paths:
  /v1/products:
    get:
      operationId: listProducts
      summary: Daftar produk skincare
      tags: [product]
      responses:
        "200":
          description: Daftar produk berhasil diambil
  /v1/products/{productId}:
    get:
      operationId: getProduct
      summary: Detail satu produk
      tags: [product]
      responses:
        "200":
          description: Produk ditemukan
        "404":
          description: Produk tidak ditemukan

Memilih method bukan soal selera, melainkan soal semantik HTTP. Method menyatakan niat operasi, dan client serta infrastruktur (cache, proxy, retry) bergantung pada makna itu. Dua sifat penting: safe (tidak mengubah state server) dan idempotent (memanggil berkali-kali memberi efek sama seperti sekali).

Inilah endpoint katalog skincare dengan method yang sesuai niatnya.

Tiga lokasi input yang berbeda peran

Input ke sebuah operasi bisa datang dari tiga lokasi: path, query string, dan header. Tiap lokasi punya peran khasnya sendiri, dan OpenAPI mendeskripsikan ketiganya lewat parameter object dengan field in.

flowchart LR
  Req["GET /v1/products/{productId}?sort=price"] --> Path["in: path -> productId (identitas resource)"]
  Req --> Query["in: query -> sort, page, q (filter dan opsi)"]
  Req --> Header["in: header -> Authorization, X-Request-ID (metadata)"]

Gambar 3. Tiga lokasi parameter dan peran masing-masing dalam satu request.

Mulai dari path parameter. Ia merepresentasikan identitas resource dan selalu bagian dari URL, misalnya productId di /v1/products/{productId}. Path parameter selalu required, karena tanpa nilainya path tidak lengkap.

api/openapi.yaml (path parameter)Salin
/v1/products/{productId}:
  get:
    operationId: getProduct
    parameters:
      - name: productId
        in: path
        required: true
        description: Identitas unik produk
        schema:
          type: integer
          format: int64
          example: 42

Query parameter cocok untuk hal yang bukan identitas: filter, search, sort, dan pagination. Untuk katalog skincare, query yang lazim adalah page, limit, sort, q (kata kunci pencarian), dan skin_type. Query parameter umumnya opsional dengan nilai default yang masuk akal.

api/openapi.yaml (query parameter)Salin
/v1/products:
  get:
    operationId: listProducts
    parameters:
      - name: q
        in: query
        required: false
        description: Kata kunci pencarian nama produk
        schema:
          type: string
          example: serum vitamin c
      - name: skin_type
        in: query
        required: false
        schema:
          type: string
          enum: [oily, dry, combination, sensitive, normal]
          example: oily
      - name: page
        in: query
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20

Request header menyampaikan metadata, bukan data bisnis: kredensial auth, idempotency key, dan trace id. Kunci penting di sini adalah selektif. Dokumentasikan header yang menjadi kontrak (yang harus dikirim atau diperhatikan client), bukan setiap header internal.

api/openapi.yaml (header parameter)Salin
/v1/checkout:
  post:
    operationId: checkout
    parameters:
      - name: Idempotency-Key
        in: header
        required: true
        description: UUID unik agar checkout tidak terjadi dua kali saat retry
        schema:
          type: string
          format: uuid
          example: 9f1c7e2a-1d4b-4a9e-8a1f-3c2b5d6e7f80
      - name: X-Request-ID
        in: header
        required: false
        description: ID korelasi untuk tracing antar service
        schema:
          type: string

Mendeskripsikan payload yang dikirim client

Saat client membuat resource, memperbarui data, login, atau checkout, ia mengirim payload. Object requestBody mendeskripsikan payload itu: apakah wajib, dalam media type apa, dan menautkannya ke schema.

Berbeda dari parameter yang tersebar di path, query, dan header, request body adalah satu kesatuan yang dikirim di body request. Field utamanya: required (apakah body wajib ada), content (peta media type ke schema), dan di dalamnya media type seperti application/json.

flowchart LR
  RB["requestBody"] --> Req["required: true/false"]
  RB --> Content["content"]
  Content --> MT["application/json"]
  MT --> Schema["schema (bentuk payload)"]

Gambar 4. Anatomi requestBody: dari flag required, ke media type, ke schema payload.

Contoh paling jelas adalah login. Client mengirim email dan password, dan body itu wajib ada. Schema-nya inline dulu untuk kejelasan; di section Components kita pindahkan ke tempat reusable.

api/openapi.yaml (request body login)Salin
/v1/auth/login:
  post:
    operationId: login
    summary: Login dengan email dan password
    tags: [auth]
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required: [email, password]
            properties:
              email:
                type: string
                format: email
                example: dina@skincare.example
              password:
                type: string
                format: password
                minLength: 8
                example: rahasiakuat123
    responses:
      "200":
        description: Login berhasil

Checkout lebih kaya. Body-nya berisi daftar item, alamat pengiriman, dan metode pembayaran. Perhatikan bagaimana schema bersarang menggambarkan struktur nyata payload.

api/openapi.yaml (request body checkout)Salin
/v1/checkout:
  post:
    operationId: checkout
    summary: Ubah keranjang jadi order
    tags: [checkout]
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required: [items, shippingAddress, paymentMethod]
            properties:
              items:
                type: array
                minItems: 1
                items:
                  type: object
                  required: [productId, quantity]
                  properties:
                    productId:
                      type: integer
                      format: int64
                    quantity:
                      type: integer
                      minimum: 1
              shippingAddress:
                type: string
                example: Jl. Melati No. 7, Bandung
              paymentMethod:
                type: string
                enum: [bank_transfer, ewallet, cod]
    responses:
      "201":
        description: Order berhasil dibuat

Mendeskripsikan semua kemungkinan hasil operasi

Kontrak yang baik tidak hanya bilang “kalau sukses, ini bentuknya”. Ia juga memprediksi kegagalan: input salah, tidak terautentikasi, resource tidak ada, konflik, validasi gagal, dan error server. Object responses mendeskripsikan semua itu.

Tiap entri di responses dikunci oleh status code HTTP, dan tiap status punya description, opsional content (body response), dan opsional headers. Menutup semua status yang realistis membuat backend dan frontend punya ekspektasi yang sama sejak awal, bukan saling kaget di production.

stateDiagram-v2
  [*] --> Validasi
  Validasi --> Auth: input valid
  Validasi --> E400: input salah (400)
  Validasi --> E422: validasi gagal (422)
  Auth --> Proses: terautentikasi
  Auth --> E401: tanpa token (401)
  Proses --> Sukses: resource ada
  Proses --> E404: tidak ditemukan (404)
  Proses --> E409: konflik stok (409)
  Proses --> E500: error server (500)
  Sukses --> [*]

Gambar 5. Satu operasi checkout bisa berakhir di banyak status. Kontrak yang baik menulis semuanya.

api/openapi.yaml (responses lengkap)Salin
/v1/checkout:
  post:
    operationId: checkout
    responses:
      "201":
        description: Order berhasil dibuat
        headers:
          Location:
            description: URL order yang baru dibuat
            schema:
              type: string
        content:
          application/json:
            schema:
              type: object
              properties:
                orderId:
                  type: integer
                  format: int64
                status:
                  type: string
                  example: pending_payment
      "401":
        description: Tidak terautentikasi
      "409":
        description: Stok tidak mencukupi
      "422":
        description: Validasi payload gagal
      "500":
        description: Kesalahan server

Mendefinisikan bentuk data dengan presisi

Sampai di sini kita banyak menulis schema inline tanpa membahas isinya. Saatnya mendalami Schema Object: bagian yang mendefinisikan bentuk data, dari tipe sampai constraint detail seperti panjang minimum dan nilai minimum.

Schema Object menjawab pertanyaan “data ini bentuknya seperti apa”: type, properties, required, nullable, enum, format, items (untuk array), serta constraint seperti minLength, maxLength, minimum, dan maximum. Inilah yang membuat spec bisa memvalidasi payload, bukan sekadar mendeskripsikannya.

Mari modelkan domain skincare. Pertama Product, dengan field id, name, dan referensi ke variant dan harga. Perhatikan constraint pada tiap field.

api/openapi.yaml (schema Product)Salin
Product:
  type: object
  required: [id, name, slug, priceRupiah, isActive]
  properties:
    id:
      type: integer
      format: int64
      example: 42
    name:
      type: string
      minLength: 1
      maxLength: 200
      example: Serum Vitamin C 20%
    slug:
      type: string
      example: serum-vitamin-c-20
    description:
      type: string
      nullable: true
    priceRupiah:
      type: integer
      format: int64
      minimum: 0
      description: Harga dalam rupiah sebagai bilangan bulat
      example: 149000
    skinTypes:
      type: array
      items:
        type: string
        enum: [oily, dry, combination, sensitive, normal]
    isActive:
      type: boolean
      example: true

ProductVariant mewakili varian (misalnya ukuran 30ml dan 50ml) yang masing-masing punya harga dan stok sendiri.

api/openapi.yaml (schema ProductVariant)Salin
ProductVariant:
  type: object
  required: [id, label, priceRupiah, stock]
  properties:
    id:
      type: integer
      format: int64
    label:
      type: string
      example: 30ml
    priceRupiah:
      type: integer
      format: int64
      minimum: 0
    stock:
      type: integer
      minimum: 0
      example: 24

Untuk uang yang punya satuan dan mata uang eksplisit, sebuah schema Money kecil membuat representasi konsisten lintas API. Ini juga jadi contoh perubahan kontrak yang kita bahas di section Topik Lanjutan.

api/openapi.yaml (schema Money)Salin
Money:
  type: object
  required: [amount, currency]
  properties:
    amount:
      type: integer
      format: int64
      minimum: 0
      description: Jumlah dalam satuan terkecil (rupiah penuh)
      example: 149000
    currency:
      type: string
      enum: [IDR]
      example: IDR

Terakhir, dasar ErrorResponse yang akan kita matangkan di section Error Standard.

api/openapi.yaml (schema ErrorResponse dasar)Salin
ErrorResponse:
  type: object
  required: [code, message]
  properties:
    code:
      type: string
      example: PRODUCT_NOT_FOUND
    message:
      type: string
      example: Produk tidak ditemukan
    requestId:
      type: string
      example: 9f1c7e2a-1d4b-4a9e-8a1f-3c2b5d6e7f80

Empat alat menjaga spec tetap maintainable

Begitu spec tumbuh, duplikasi jadi musuh. Schema Product yang ditulis ulang di lima tempat akan menyimpang diam-diam. Empat alat ini menjaga spec tetap ramping dan mudah dinavigasi: components, $ref, examples, dan tags.

components adalah lemari penyimpanan objek reusable: schemas, parameters, responses, dan securitySchemes. Setelah objek diletakkan di sana, ia dirujuk dari mana saja dengan $ref, sebuah pointer ke lokasi definisi. Tidak ada lagi salin-tempel.

api/openapi.yaml (components dan $ref)Salin
paths:
  /v1/products/{productId}:
    get:
      operationId: getProduct
      responses:
        "200":
          description: Produk ditemukan
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Product"
        "404":
          $ref: "#/components/responses/NotFound"
components:
  schemas:
    Product:
      type: object
      required: [id, name]
      properties:
        id: { type: integer, format: int64 }
        name: { type: string }
  responses:
    NotFound:
      description: Resource tidak ditemukan
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

examples membuat spec terasa nyata. Sebuah schema memberi tahu bentuk, tetapi example memberi tahu rupanya. Kamu bisa menaruh satu example di schema, atau beberapa examples bernama di media type untuk menunjukkan kasus berbeda. Example juga jadi bahan dasar mock server.

api/openapi.yaml (examples bernama)Salin
content:
  application/json:
    schema:
      $ref: "#/components/schemas/Product"
    examples:
      serum:
        summary: Serum vitamin C
        value:
          id: 42
          name: Serum Vitamin C 20%
          priceRupiah: 149000
      sunscreen:
        summary: Sunscreen SPF 50
        value:
          id: 77
          name: Daily Sunscreen SPF 50 PA++++
          priceRupiah: 99000

tags mengelompokkan operation per domain agar dokumentasi tidak jadi daftar endpoint mentah yang panjang. Untuk skincare shop, kelompokkan per domain: product, cart, checkout, order, auth, dan admin.

api/openapi.yaml (tags)Salin
tags:
  - name: product
    description: Katalog produk dan pencarian
  - name: cart
    description: Keranjang belanja
  - name: checkout
    description: Proses checkout jadi order
  - name: order
    description: Riwayat dan status order
  - name: auth
    description: Login, register, dan sesi
  - name: admin
    description: Operasi khusus admin

Satu bentuk error yang konsisten lintas endpoint

Bila tiap endpoint mengembalikan error dengan bentuk berbeda, frontend, mobile, dan QA terpaksa menebak. Error standard yang konsisten membuat penanganan error bisa ditulis sekali dan dipakai di mana saja.

Bentuk error yang baik membawa minimal: kode mesin yang stabil (code), pesan untuk manusia (message), detail validasi per field bila ada (fields), dan id request untuk korelasi log (requestId). Kode mesin penting karena pesan bisa berubah kata-katanya, tetapi code jadi pegangan logika di client.

api/openapi.yaml (ErrorResponse dan ValidationErrorResponse)Salin
components:
  schemas:
    ErrorResponse:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
          example: PRODUCT_NOT_FOUND
        message:
          type: string
          example: Produk tidak ditemukan
        requestId:
          type: string
          format: uuid
    ValidationErrorResponse:
      type: object
      required: [code, message, fields]
      properties:
        code:
          type: string
          example: VALIDATION_FAILED
        message:
          type: string
          example: Beberapa field tidak valid
        fields:
          type: array
          items:
            type: object
            required: [field, message]
            properties:
              field:
                type: string
                example: email
              message:
                type: string
                example: Format email tidak valid
        requestId:
          type: string
          format: uuid

Untuk standar industri yang matang, ada RFC 9457 (Problem Details for HTTP APIs). Ia mendefinisikan media type application/problem+json dengan field standar type, title, status, detail, dan instance, plus extension seperti errors. RFC ini menggantikan RFC 7807 dan layak jadi acuan saat kamu ingin bentuk error yang interoperable lintas organisasi. Lihat RFC 9457 untuk teks lengkapnya.

api/openapi.yaml (Problem Details ala RFC 9457)Salin
components:
  schemas:
    Problem:
      type: object
      properties:
        type:
          type: string
          format: uri
          example: https://skincare.example/problems/out-of-stock
        title:
          type: string
          example: Stok tidak mencukupi
        status:
          type: integer
          example: 409
        detail:
          type: string
          example: Varian 30ml dari produk 42 sudah habis
        instance:
          type: string
          example: /v1/checkout

Contoh response Problem DetailsSalin
HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{
  "type": "https://skincare.example/problems/out-of-stock",
  "title": "Stok tidak mencukupi",
  "status": 409,
  "detail": "Varian 30ml dari produk 42 sudah habis",
  "instance": "/v1/checkout"
}

Mendokumentasikan autentikasi dengan jelas

API nyata punya endpoint publik (daftar produk) dan terproteksi (checkout, order). components.securitySchemes mendokumentasikan cara autentikasi, dan field security menerapkannya secara global atau per operasi.

OpenAPI mendukung beberapa jenis skema keamanan. Yang paling umum di backend Go: bearer token (JWT) lewat header Authorization, API key lewat header khusus, dan OAuth2 untuk alur yang lebih kompleks. Definisikan skemanya sekali di components.securitySchemes, lalu rujuk dengan namanya.

api/openapi.yaml (securitySchemes)Salin
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT pada header Authorization, format "Bearer <token>"
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key untuk integrasi server ke server

Penerapan keamanan bertingkat. security di level top-level berlaku untuk semua operasi sebagai default. Operasi tertentu bisa override, termasuk membuat dirinya publik dengan security: [] (array kosong berarti tidak butuh auth).

api/openapi.yaml (security global dan override)Salin
security:
  - bearerAuth: []
paths:
  /v1/products:
    get:
      operationId: listProducts
      summary: Daftar produk (publik)
      security: []
      responses:
        "200":
          description: Daftar produk
  /v1/checkout:
    post:
      operationId: checkout
      summary: Checkout (butuh login)
      responses:
        "201":
          description: Order dibuat
        "401":
          description: Tidak terautentikasi

flowchart TD
  Global["security global: bearerAuth"] --> List["GET /v1/products -> override security: [] (publik)"]
  Global --> Checkout["POST /v1/checkout -> pakai default (butuh JWT)"]
  Global --> Orders["GET /v1/orders -> pakai default (butuh JWT)"]

Gambar 6. Security global jadi default; daftar produk override menjadi publik, sedangkan checkout dan order tetap terproteksi.

Menyatukan semua konsep jadi satu kontrak utuh

Sekarang seluruh konsep berkumpul. Inilah blueprint openapi.yaml untuk MVP online shop skincare: katalog, cart, checkout, order, auth, dan admin, dengan tags domain, shared schemas, error standard, security, dan examples.

Sebelum melihat YAML utuh, ini struktur folder tempat spec hidup di proyek Go. Spec berdiri sendiri di api/, terpisah dari kode implementasi.

Inilah daftar endpoint MVP, dikelompokkan per domain. Publik vs terproteksi ditandai oleh ada tidaknya kebutuhan auth.

Dan inilah kerangka spec yang menyatukan semuanya. Sengaja dipangkas pada bagian berulang, tetapi strukturnya utuh dan valid sebagai blueprint.

api/openapi.yaml (blueprint MVP)Salin
openapi: 3.1.1
info:
  title: Skincare Shop API
  version: 1.0.0
  description: Kontrak HTTP untuk backend online shop skincare (MVP).
servers:
  - url: http://localhost:8080
    description: Local development
  - url: https://api.skincare.example
    description: Production
security:
  - bearerAuth: []
tags:
  - name: product
  - name: cart
  - name: checkout
  - name: order
  - name: auth
  - name: admin
paths:
  /v1/products:
    get:
      operationId: listProducts
      summary: Daftar produk
      tags: [product]
      security: []
      parameters:
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/Limit"
        - name: skin_type
          in: query
          schema:
            type: string
            enum: [oily, dry, combination, sensitive, normal]
      responses:
        "200":
          description: Daftar produk
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Product"
  /v1/products/{productId}:
    get:
      operationId: getProduct
      summary: Detail produk
      tags: [product]
      security: []
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: Produk ditemukan
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Product"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/auth/login:
    post:
      operationId: login
      summary: Login
      tags: [auth]
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email: { type: string, format: email }
                password: { type: string, minLength: 8 }
      responses:
        "200":
          description: Login berhasil
        "422":
          $ref: "#/components/responses/ValidationError"
  /v1/checkout:
    post:
      operationId: checkout
      summary: Checkout
      tags: [checkout]
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CheckoutRequest"
      responses:
        "201":
          description: Order dibuat
        "401":
          $ref: "#/components/responses/Unauthorized"
        "409":
          $ref: "#/components/responses/Conflict"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    Page:
      name: page
      in: query
      schema: { type: integer, minimum: 1, default: 1 }
    Limit:
      name: limit
      in: query
      schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
  responses:
    NotFound:
      description: Resource tidak ditemukan
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    Unauthorized:
      description: Tidak terautentikasi
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    Conflict:
      description: Konflik dengan state saat ini
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    ValidationError:
      description: Validasi gagal
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ValidationErrorResponse"
  schemas:
    Product:
      type: object
      required: [id, name, priceRupiah, isActive]
      properties:
        id: { type: integer, format: int64 }
        name: { type: string, minLength: 1, maxLength: 200 }
        priceRupiah: { type: integer, format: int64, minimum: 0 }
        isActive: { type: boolean }
    CheckoutRequest:
      type: object
      required: [items, paymentMethod]
      properties:
        items:
          type: array
          minItems: 1
          items:
            type: object
            required: [productId, quantity]
            properties:
              productId: { type: integer, format: int64 }
              quantity: { type: integer, minimum: 1 }
        paymentMethod:
          type: string
          enum: [bank_transfer, ewallet, cod]
    ErrorResponse:
      type: object
      required: [code, message]
      properties:
        code: { type: string }
        message: { type: string }
        requestId: { type: string, format: uuid }
    ValidationErrorResponse:
      type: object
      required: [code, message, fields]
      properties:
        code: { type: string }
        message: { type: string }
        fields:
          type: array
          items:
            type: object
            required: [field, message]
            properties:
              field: { type: string }
              message: { type: string }

Yang sengaja ditunda agar tidak hilang diam-diam

Course ini fokus pada menulis kontrak. Ada banyak topik kuat di sekitar OpenAPI yang sengaja ditunda agar fondasi kontrak ini kuat dulu. Berikut peta singkatnya supaya tidak ada yang hilang.

Dua catatan teknis untuk Go yang sering ditanyakan lebih awal: ada dua pendekatan utama menghubungkan OpenAPI dengan kode Go, masing-masing punya filosofi berbeda.

Terminal (instalasi oapi-codegen)Salin
go install github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@latest

Benang merah dan jalan ke implementasi

Satu benang merah mengikat seluruh course: paths, operations, parameter, request body, responses, schema, components, security, dan examples bukan bagian-bagian terpisah, melainkan satu kontrak yang bisa diverifikasi.

Kita mulai dari motivasi (OpenAPI sebagai kontrak machine-readable, bukan dokumentasi cantik), membangun mental model struktur dokumen, lalu mengisi tiap bagian: identitas dan server, endpoint dan method, tiga lokasi parameter, request body, response yang menutup error, schema yang presisi, components untuk reuse, error standard, dan security. Semuanya berpuncak pada satu blueprint openapi.yaml untuk online shop skincare.

flowchart LR
  Spec["openapi.yaml (kontrak)"] --> Impl["Implementasi Go: net/http + chi"]
  Impl --> Validation["Handler validation"]
  Validation --> CI["CI contract check"]
  Spec --> CI
  CI --> Prod["API production yang sesuai kontrak"]

Gambar 7. Dari kontrak ke implementasi: spec memandu handler, dan CI menjaga keduanya selaras.

Langkah berikutnya jelas: dari menulis spec, kamu masuk ke implementasi. Bangun handler dengan net/http dan chi, tegakkan validasi sesuai schema, lalu pasang contract check di CI agar kode dan kontrak tidak pernah menyimpang. Untuk mendalami codegen dan integrasi Go, lihat oapi-codegen. Dengan kontrak yang kokoh sebagai fondasi, sisa jalur Web Artisan, dari routing sampai deploy ke AWS, berdiri di atas dasar yang sudah disepakati bersama.