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:
- Ingin embed dokumentasi dalam style internal (portal developer kita sendiri).
- Perlu menambah detail bisnis, remark, atau scenario.
- 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:
1import "github.com/graphql-go/graphql"
2
3var userType = graphql.NewObject(graphql.ObjectConfig{
4 Name: "User",
5 Fields: graphql.Fields{
6 "id": &graphql.Field{
7 Type: graphql.String,
8 Description: "Unique identifier of the user",
9 },
10 "name": &graphql.Field{
11 Type: graphql.String,
12 Description: "The user's full name",
13 },
14 },
15})
16
17var rootQuery = graphql.NewObject(graphql.ObjectConfig{
18 Name: "Query",
19 Fields: graphql.Fields {
20 "user": &graphql.Field{
21 Type: userType,
22 Description: "Find a user by ID",
23 Args: graphql.FieldConfigArgument{
24 "id": &graphql.ArgumentConfig{
25 Type: graphql.NewNonNull(graphql.String),
26 },
27 },
28 Resolve: /* implement resolver... */
29 },
30 },
31})
32
33var schema, _ = graphql.NewSchema(graphql.SchemaConfig{
34 Query: rootQuery,
35})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:
1query IntrospectionQuery {
2 __schema {
3 types {
4 name
5 description
6 fields {
7 name
8 description
9 args {
10 name
11 description
12 type {
13 name
14 kind
15 }
16 }
17 type {
18 name
19 kind
20 }
21 }
22 }
23 }
24}Contohnya di Go:
1params := graphql.Params{
2 Schema: schema,
3 RequestString: introspectionQuery,
4}
5
6result := graphql.Do(params)
7resultJSON, _ := json.MarshalIndent(result, "", " ")
8fmt.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:
1package main
2
3import (
4 "encoding/json"
5 "io/ioutil"
6 "os"
7)
8
9type IntrospectionResult struct {
10 Data struct {
11 Schema struct {
12 Types []struct {
13 Name string `json:"name"`
14 Description string `json:"description"`
15 Fields []struct {
16 Name string `json:"name"`
17 Description string `json:"description"`
18 } `json:"fields"`
19 } `json:"types"`
20 } `json:"__schema"`
21 } `json:"data"`
22}
23
24func main() {
25 // Baca file hasil introspeksi
26 data, _ := ioutil.ReadFile("schema.json")
27 var result IntrospectionResult
28 json.Unmarshal(data, &result)
29
30 f, _ := os.Create("DOCS.md")
31 defer f.Close()
32
33 f.WriteString("# API Documentation\n")
34 for _, t := range result.Data.Schema.Types {
35 if t.Description != "" && len(t.Fields) > 0 {
36 f.WriteString("## " + t.Name + "\n" + t.Description + "\n")
37 for _, field := range t.Fields {
38 f.WriteString("- **" + field.Name + "**: " + field.Description + "\n")
39 }
40 f.WriteString("\n")
41 }
42 }
43}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:
1var userType = graphql.NewObject(graphql.ObjectConfig{
2 Name: "User",
3 Fields: graphql.Fields{
4 "email": &graphql.Field{
5 Type: graphql.String,
6 Description: `The user's main email.
7@format: email
8@example: user@example.com
9@remark: Only verified emails shown.`,
10 },
11 },
12})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:
| Field | Description | Format | Example | Remark |
|---|---|---|---|---|
| The user’s main email | user@example.com | Only verified emails shown. | ||
| name | The user’s full name | (none) | (none) | (none) |
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]
- Build: Build code & schema.
- Execute_Introspection: Otomasi dump schema JSON.
- Generate_Docs: Jalankan generator untuk output HTML/Markdown.
- 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! 🚀