73 Membangun Sistem Auto-docs di graphql-go

Saat organisasi tumbuh, satu hal yang umumnya berkembang dengan cepat (dan seringkali buruk) adalah dokumentasi API. GraphQL menawarkan keunggulan dengan introspeksi skema yang sudah built-in, namun dokumentasi yang baik tetap harus dilengkapi penjelasan bisnis dan contoh kasus nyata. Di artikel ini, saya ingin mengajak kamu membangun auto-docs system —dokumentasi otomatis—untuk GraphQL API berbasis graphql-go. Dengan pendekatan ini, kita ingin mengurangi gap antara kode dan dokumentasi: apa yang berubah di kode otomatis tercermin di dokumentasi.

Mengapa Auto-Docs?

Auto-docs pada GraphQL bukan barang baru. Platform seperti Apollo, GraphQL Voyager, ataupun GraphiQL, sudah banyak memberikan exploration tools. Namun, tantangan muncul jika kita:

1. Ingin embed dokumentasi dalam style internal (portal developer kita sendiri).
2. Perlu menambah detail bisnis, remark, atau scenario.
3. Menyediakan dokumentasi up-to-date (bukan copy-paste schema setahun lalu).

Jika kamu memakai graphql-go, fungsi introspeksi sudah tersedia—namun hasilnya masih dalam bentuk data mentah yang kurang informatif bagi end-user atau developer.

Arsitektur Sistem Auto-Docs

Sebelum implementasi, kita susun diagram alur sederhananya berikut:

flowchart TD
    A[Source Code] --> B(GraphQL Schema & Resolvers)
    B --> C[Introspection Query]
    C --> D[Schema JSON]
    D --> E[Docs Generator]
    E --> F[Human-friendly HTML/Markdown Docs]

Penjelasan sederhananya:

• Source Code: kamu mendefinisikan schema dan resolver di Go.
• Introspection Query: tool melakukan query introspeksi pada *graphql.Schema.
• Docs Generator: script builder yang membaca hasil introspeksi + custom annotation dari kode kamu.
• Output: Dokumen friendly dalam HTML/Markdown yang bisa dideploy.

Mari kita breakdown langkah per langkah.

Setting up graphql-go Schema

Biasanya, kamu akan setup schema seperti ini:

import "github.com/graphql-go/graphql"

var userType = graphql.NewObject(graphql.ObjectConfig{
    Name: "User",
    Fields: graphql.Fields{
        "id": &graphql.Field{
            Type: graphql.String,
            Description: "Unique identifier of the user",
        },
        "name": &graphql.Field{
            Type: graphql.String,
            Description: "The user's full name",
        },
    },
})

var rootQuery = graphql.NewObject(graphql.ObjectConfig{
    Name: "Query",
    Fields: graphql.Fields {
        "user": &graphql.Field{
            Type: userType,
            Description: "Find a user by ID",
            Args: graphql.FieldConfigArgument{
                "id": &graphql.ArgumentConfig{
                    Type: graphql.NewNonNull(graphql.String),
                },
            },
            Resolve: /* implement resolver... */
        },
    },
})

var schema, _ = graphql.NewSchema(graphql.SchemaConfig{
    Query: rootQuery,
})

Catatan: Description pada tiap type/field jadi kunci agar dokumentasi kita informatif.

Menjalankan Introspeksi untuk Mendapatkan Skema

Untuk membuat auto-docs, pertama kita butuh data introspeksi.

Buat endpoint GraphQL yang menerima query introspeksi berikut:

query IntrospectionQuery {
    __schema {
        types {
            name
            description
            fields {
                name
                description
                args {
                    name
                    description
                    type {
                        name
                        kind
                    }
                }
                type {
                    name
                    kind
                }
            }
        }
    }
}

Contohnya di Go:

params := graphql.Params{
    Schema: schema,
    RequestString: introspectionQuery,
}

result := graphql.Do(params)
resultJSON, _ := json.MarshalIndent(result, "", "  ")
fmt.Println(string(resultJSON))

Outputnya berupa JSON yang bisa kamu konsumsi untuk proses selanjutnya.

Membuat Generator Auto-Docs

Bagian kunci berikutnya adalah generator—sebuah script yang mengubah JSON introspeksi menjadi file Markdown/HTML yang rapi. Berikut adalah contoh sederhana di Go untuk mengubah output introspeksi menjadi Markdown:

package main

import (
    "encoding/json"
    "io/ioutil"
    "os"
)

type IntrospectionResult struct {
    Data struct {
        Schema struct {
            Types []struct {
                Name        string `json:"name"`
                Description string `json:"description"`
                Fields      []struct {
                    Name        string `json:"name"`
                    Description string `json:"description"`
                } `json:"fields"`
            } `json:"types"`
        } `json:"__schema"`
    } `json:"data"`
}

func main() {
    // Baca file hasil introspeksi
    data, _ := ioutil.ReadFile("schema.json")
    var result IntrospectionResult
    json.Unmarshal(data, &result)
    
    f, _ := os.Create("DOCS.md")
    defer f.Close()

    f.WriteString("# API Documentation\n")
    for _, t := range result.Data.Schema.Types {
        if t.Description != "" && len(t.Fields) > 0 {
            f.WriteString("## " + t.Name + "\n" + t.Description + "\n")
            for _, field := range t.Fields {
                f.WriteString("- **" + field.Name + "**: " + field.Description + "\n")
            }
            f.WriteString("\n")
        }
    }
}

Hasilnya adalah dokumen Markdown yang auto-update jika schema berubah.

Menambah Custom Annotation (Simulasi)

Mungkin kamu ingin menambahkan contoh, format, atau remark lainnya. Untuk itu, tim kita biasa memakai pola meng-embed tag custom ke Description:

var userType = graphql.NewObject(graphql.ObjectConfig{
    Name: "User",
    Fields: graphql.Fields{
        "email": &graphql.Field{
            Type: graphql.String,
            Description: `The user's main email.
@format: email
@example: user@example.com
@remark: Only verified emails shown.`,
        },
    },
})

Kemudian, di generator docs, bisa dilakukan parsing sederhana split by @ untuk mengelompokkan informasi itu. Ini memungkinkan scaling dokumentasi tanpa perlu mengubah struktur skema.

Hasil Simulasi dan Tabel Dokumen

Mari simulasikan output docs:

Ini jauh lebih membantu untuk pengembang frontend atau QA, dibanding hanya membaca raw introspection.

Pipeline CI/CD Auto-Docs

Best-practice: proses auto-docs ini sebaiknya terotomasi dalam pipeline CI/CD.

graph TD
    CodeBase --> Build
    Build --> Execute_Introspection
    Execute_Introspection --> Generate_Docs
    Generate_Docs --> DeployDocs[Deploy to Docs Portal]

1. Build: Build code & schema.
2. Execute_Introspection: Otomasi dump schema JSON.
3. Generate_Docs: Jalankan generator untuk output HTML/Markdown.
4. Deploy: Push ke portal documentation (bisa Github Pages, S3, Web Portal, dsb).

Dengan cara ini, dokumen selalu up-to-date, tanpa perlu manual copy-paste.

Penutup: Auto-Docs, Simple Tapi Powerful

Jalan menuju dokumentasi API yang baik belum selesai hanya dengan auto-docs. Pendekatan ini tidak menggantikan best-practice dokumentasi manual, terutama untuk penjelasan bisnis, skenario edge case, dan relationship antar resource.

Namun, dari pengalaman, sistem auto-docs semacam ini:

• Memotong waktu lead time update docs saat schema berubah,
• Mengurangi kebingungan antar tim,
• Mengurangi bug akibat dokumentasi tidak sinkron dengan implementasi.

Integrasi sistem auto-docs sangat feasible dengan graphql-go tanpa menambah dependency besar. Framework ini bahkan bisa kamu gunakan sebagai foundation untuk portal developer yang lebih advance di masa depan.

Punya pengalaman atau tips auto-docs lain? Sharing di kolom komentar! 🚀