71 Menulis Dokumentasi Skema Secara Otomatis

Dokumentasi sering dianggap “tugas sampingan” yang membosankan, tetapi hampir setiap engineer senior sepakat: dokumentasi adalah investasi. Salah satu dokumentasi terpenting adalah dokumentasi skema database atau API, yang sering kali cepat usang jika di-maintain secara manual. Beruntung, tools modern sudah menawarkan cara otomatis dan efisien menulis dokumentasi skema. Dalam artikel ini, saya akan membahas 71 tips, teknik, serta contoh real mengenai otomatisasi penulisan dokumentasi skema, khususnya untuk database dan API, dengan pendekatan yang bisa langsung Anda praktikkan di proyek sehari-hari.

Mengapa Dokumentasi Skema Penting?

Pernahkah Anda mewarisi proyek dengan database tanpa dokumentasi? Atau mengintegrasikan API yang hanya punya file Swagger lawas, tanpa deskripsi yang jelas? Berikut adalah masalah nyata yang muncul:

• Mempersulit onboarding engineer baru
• Rawan miscommunication antar tim
• Membuat debugging menjadi lebih lama
• Melambatkan pengembangan fitur baru

Dengan dokumentasi skema yang baik, semua itu bisa diminimalkan. Namun, kebutuhan akan update cepat dan keterbatasan waktu engineer menyebabkan dokumentasi sering terabaikan.

Opsi Otomatisasi Dokumentasi Skema

Terdapat beragam tooling yang memungkinkan kita meng-generate dokumentasi skema secara otomatis. Saya akan zoom in ke dua use-case utama: database schema (misal: PostgreSQL) dan API schema (misal: RESTful API dengan OpenAPI).

1. Database Schema

Database modern seperti PostgreSQL menyimpan seluruh metadata skema-nya di dalam information schema. Tools seperti dbdocs.io, SchemaSpy, atau PostgreSQL Autodoc bisa membaca metadata tersebut dan mengubahnya jadi dokumen visual dan naratif.

Contoh: Menggunakan SchemaSpy untuk PostgreSQL

Misalkan kita punya schema berikut:

CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    email VARCHAR(255) UNIQUE NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);

CREATE TABLE posts (
    id SERIAL PRIMARY KEY,
    user_id INTEGER REFERENCES users(id),
    title VARCHAR(255),
    body TEXT,
    published_at TIMESTAMP
);

Menggunakan SchemaSpy sangat sederhana:

docker run --rm -v $PWD:/output schemaspy/schemaspy \
  -t pgsql \
  -dp /drivers/postgresql-*.jar \
  -db mydb -host db.example.com -u dbuser -p secret \
  -o /output

Hasilnya adalah dokumentasi HTML yang berisi:

• Tabel relasi
• Deskripsi kolom (jika ada comments)
• ER diagram interaktif

Tabel Hasil Ekstraksi

Catatan: Anda bisa menambahkan deskripsi pada kolom dengan perintah SQL seperti COMMENT ON COLUMN users.email IS 'Alamat email utama pengguna'; agar dokumentasi yang dihasilkan lebih bermakna.

Flow Diagram Proses Otomatisasi

flowchart LR
    A["Perbarui Schema Database"] --> B["Jalankan SchemaSpy"]
    B --> C["Read Metadata"]
    C --> D["Generate HTML Documentation"]
    D --> E["Team Review"]

2. API Schema Documentation

Jika Anda mengembangkan API (REST, GraphQL), lebih baik menulis spesifikasi API secara deklaratif menggunakan format seperti OpenAPI/Swagger atau GraphQL SDL. Dari spesifikasi inilah, dokumentasi otomatis dihasilkan.

Contoh: Menggunakan Swagger/OpenAPI Autogeneration

Misal, Anda menggunakan Node.js dengan Express & Typescript:

import express from 'express';
import swaggerUi from 'swagger-ui-express';
import swaggerJsdoc from 'swagger-jsdoc';

const app = express();

const options = {
  definition: {
    openapi: '3.0.0',
    info: { title: 'My API', version: '1.0.0' },
  },
  apis: ['./routes/*.ts'],
};

const swaggerSpec = swaggerJsdoc(options);
app.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

Lalu di file route:

/**
 * @openapi
 * /users:
 *   get:
 *     summary: Get all users
 *     tags:
 *       - Users
 *     responses:
 *       200:
 *         description: List of users
 */
app.get('/users', getAllUsersHandler);

Kunjungi /docs – voila! Dokumentasi interaktif siap digunakan developer lain.

Tools seperti Redoc dan Swagger Editor sangat membantu mempercantik tampilan.

Kelebihan

• Selalu update: Setiap perubahan code akan tercermin di dokumentasi.
• Testing otomatis: Banyak tool yang bisa auto-match dokumentasi vs implementasi.

Cara Memastikan Dokumentasi Selalu Up-to-date

Automasi bukan solusi ajaib jika prosesnya tidak terintegrasi. Berikut tips agar dokumentasi skema tetap relevan dan tidak “busuk”:

a. Integrasi di CI/CD

Setiap push ke branch utama, tambahkan job untuk mengenerate dokumentasi terbaru, misalnya:

# .github/workflows/build-docs.yml
name: Build & Deploy Docs
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Generate DB Docs
        run: docker run ... schemaspy ...
      - name: Publish Docs
        uses: peaceiris/actions-gh-pages@v3
        with:
          publish_dir: ./output

b. “Docs as Code” Culture

Selalu treat dokumentasi sebagai bagian dari codebase: pull request yang mengubah skema harus mengupdate dokumentasi—lebih gampang jika ada pipeline otomatis.

c. Validasi Konsistensi Skema & Dokumentasi

Ada tools seperti spectral untuk OpenAPI yang bisa mengunci agar dokumentasi sesuai dengan code implementation.

Simulasi: Studi Kasus Mini

Misalkan Anda punya aplikasi blog kecil dan ingin mendokumentasikan skemanya, baik database maupun API secara otomatis.

1. Database: Gunakan SchemaSpy seperti contoh di atas. Commit /output/docs ke repo Anda.
2. API: Terapkan JSDoc annotation di setiap endpoint.
3. CI Pipeline: Gabung proses di atas agar setiap merge request selalu memicu update dokumentasi.
4. Review: Tim QA/PM tinggal akses folder /docs di repo atau di hosting tertentu.

Benefit:

• Q/A dan PM bisa melihat field apa saja sebelum tanya ke backend engineer.
• Frontend engineer langsung tahu schema response tanpa harus menebak (atau galau karena field sering berubah).
• Dokumentasi menjadi bagian dari SDLC, bukan after-thought.

Kesimpulan

Menulis dokumentasi skema secara otomatis bukan berarti meniadakan peran engineer dalam menjelaskan hal yang samar—tapi membebaskan waktu dari proses-proses yang mudah diotomasi. Setelah memanfaatkan tool semacam ini, Anda akan sadar: dokumentasi bukan lagi beban, melainkan katalis kolaborasi.

Mulai hari ini, pilih automation tool yang cocok dengan stack Anda. Lakukan integrasi perlahan ke dalam workflow. Lama-lama, Anda tidak akan pernah punya “legacy schema” yang misterius lagi.

Pertanyaan dan tips tambahan? Silakan share pengalaman Anda mengotomasi dokumentasi lewat kolom komentar di bawah ✨