API Specification Editor

Terdapat dua bagian besar pada halaman ini:

• Data Model
• Spesifikasi API

Data model berisi daftar tabel, enumerasi, dan relasi basis data dalam format DBML. Pada halaman ini DBML tidak dapat diubah, jika ingin melakukan perubahan maka kembali ke DBML Editor untuk mengubah.

Spesifikasi API ditulis dalam format mirip dengan Open API Specification. Spesifikasi ditulis dengan syntax YAML dibagi menjadi tiga bagian besar:

• Metadata
• Paths (Daftar Endpoint)
• Schemas (Daftar Skema)

Metadata

Berisi informasi mengenai spesifikasi API.

title: contoh judul (wajib)
description: contoh deskripsi (opsional)
summary: contoh ringkasan (opsional)
terms_of_service: alamat url syarat ketentuan (opsional)
base_path: alamat url base_path (opsional)
version: versi spesifikasi (opsional)
contact: objek Contact (opsional)
  name: ...
  url: ...
  email: ...
license: objek License (opsional)
  name: ...
  url: ...
  identifier: ...
servers: objek Server (opsional)
  url: ...
  description: ...

Paths (Daftar Endpoint)

Berisi daftar API yang dideskripsikan pada Flowchart Builder sebelumnya. Setiap kali terdapat perubahan API pada flowchart, lakukan Import perubahan melalui tombol di kanan atas.

Ketika melakukan import, dialog popup diff akan muncul dapat memberikan daftar perubahan yang berasal dari flowchart. Jika terdapat perubahan yang tidak sesuai, maka lakukan perubahan pada halaman Flowchart Builder. Jika perubahan telah sesuai, pilih Apply untuk mengaplikasikan perubahan pada spesifikasi saat ini.

Paths

Daftar API ditaruh pada objek paths diikuti dengan nama endpoint dari API. Pada setiap endpoint, metode endpoint dituliskan sebagai anak (child) dari endpoint.

Contoh: endpoint POST /login, GET /user, PUT /user, GET /user/:id, DELETE /user/:id dituliskan sbb:

paths:
  /login:
    post:
      ...
 
  /user:
    get:
      ...
    put:
      ...
 
  /user/:id:
    get:
      ...
    delete:
      ...

Summary (opsional)

Ketika melakukan import API dari flowchart, deskripsi API akan ditampilkan pada bagian summary.

paths:
  /daftar:
    post:
      summary: |-
        Mendaftarkan pengguna
        baru

Parameters (opsional)

Pada API yang baru saja di-import, objek parameters tidak terdefinisi. Pengguna wajib melengkapi objek parameters dengan daftar parameter yang dibutuhkan oleh API terkait.

path:
  <enp>:
    <mtd>:
      ...
      parameters:
        authorization:
          type: string
          required: true
          in: header
        data:
          type: PayloadDaftar
          required: true
          in: body
        list_module_id:
          type: number
          required: true
          array: true
          in: body
        metadata:
          type: object
          required: true
          children:
            key:
              type: string
              required: true
            value:
              type: string
              required: true
        meeting_type:
          type: enum
          enum:
            - OFFLINE
            - ONLINE
          required: true
          in: query

Objek parameter diisi dengan format objek key string dengan key adalah nama parameter. Key diikuti oleh objek spesifikasi parameter dengan aturan berikut:

Children

Objek Children berisi data mirip dengan objek parameter namun tanpa key in. Objek ini mendukung data yang mengandung jenis Children itu sendiri (nested).

Return (wajib)

Objek return berjenis sama seperti object Children.

paths:
  <enp>:
    <mtd>:
      ...
      return:
        type: string
        required: true

Tags (opsional)

Objek tag diisi dengan larik array.

paths:
  <enp>:
    <mtd>:
      ...
      tags:
        - users
        - register

Consumes (opsional)

Objek consumes diisi dengan larik array.

paths:
  <enp>:
    <mtd>:
      ...
      consumes:
        - application/json
        - multipart/form-data

Produces (opsional)

Objek produces diisi dengan larik array.

paths:
  <enp>:
    <mtd>:
      ...
      produces:
        - application/json

Schemas (Daftar Skema)

Daftar skema penting digunakan sebagai struktur data penampung data pada frontend sebelum dikirim ke backend. Skema ditulis dengan format sama seperti objek Children namun didahului dengan objek properties.

schemas:
  PayloadDaftar:
    properties:
      email:
        type: string
        required: true
      name:
        type: string
        required: true
      password:
        type: string
        required: true
  AnotherSchema:
    properties:
      some_key:
        type: string
      another_key:
        type: string
        required: true

Best Practice