Skip to content
Santekno.com | Level Up Your Engineering Skills
ID
📖 0%
19 Aug 2025 · 5 mnt baca ·Artikel 72 / 110
Go

72. Generate Swagger/OpenAPI dari Protobuf

IH
Ihsan Arif
Penulis di Santekno · Backend Engineer

title: “72. Generate Swagger/OpenAPI dari Protobuf: Langkah Demi Langkah Otomatisasi Dokumentasi API” date: 2024-06-13 author: “Rahmat Adi Putra”

Bagi banyak engineer, menjalankan dokumentasi API yang tetap update seiring perubahan codebase adalah sebuah tantangan tersendiri. Dokumentasi manual seringkali menjadi sumber ketinggalan informasi. Untungnya, dunia Cloud Native menawarkan berbagai solusi otomatisasi. Salah satunya: generate spesifikasi Swagger/OpenAPI langsung dari definisi Protocol Buffer (Protobuf). Artikel ini membahas bagaimana proses tersebut dilakukan, lengkap dengan diagram alur, contoh kode .proto, konfigurasi plugin, dan simulasi output.

Mengapa Swagger/OpenAPI & Protobuf?

Protobuf adalah format serialisasi data berdampak tinggi yang menjadi tulang punggung komunikasi pada ekosistem gRPC. Sementara itu, Swagger/OpenAPI telah menjadi standar industri untuk dokumentasi API berbasis RESTful. Namun, ketika satu tim mengimplementasi service dengan gRPC (Protobuf), dan tim klien membutuhkan dokumentasi OpenAPI (Swagger), seringkali kita tergoda memperbarui dua sumber kebenaran secara manual — celah besar terbuka untuk inkonsistensi.

Solusinya: Generate OpenAPI secara otomatis dari Protobuf!

Arsitektur Otomasi: Diagram Alur

Mari kita perjelas workflow-nya dengan diagram alur berikut:

MERMAID
flowchart TD
    A[.proto file] --> B[protoc compiler]
    B --> C[protoc-gen-openapiv2 plugin]
    C --> D[openapi v2 json/swagger.yaml]

Sederhananya:

  1. Definisikan API dan message di file .proto.
  2. Kompilasi dengan protoc menggunakan plugin protoc-gen-openapiv2.
  3. Plugin mengubah service dan pesan Protobuf menjadi file Swagger/OpenAPI specification (YAML/JSON).

Studi Kasus: Service gRPC Sederhana

Contoh file .proto:

proto
 1// service.proto
 2syntax = "proto3";
 3
 4package greet;
 5
 6service Greeter {
 7  rpc SayHello (HelloRequest) returns (HelloReply) {
 8    option (google.api.http) = {
 9      post: "/v1/hello"
10      body: "*"
11    };
12  }
13}
14
15message HelloRequest {
16  string name = 1;
17}
18
19message HelloReply {
20  string message = 1;
21}
Danger
Catatan: Option (google.api.http) penting untuk mapping endpoint gRPC ke REST.

Toolchain yang Dibutuhkan

ToolVersi MinimumKeterangan
protoc3.xCompiler utama untuk .proto
protoc-gen-openapiv2TerbaruPlugin konversi Proto -> OpenAPI
grpc-gateway2.x/3.xMembantu bridging gRPC <-> REST optional
Go (jika dari source)1.18+Untuk build plugin dari source

Instalasi plugin: protoc-gen-openapiv2

Cara Instalasi

a. Download Binary (Rekomendasi di CI/CD)

sh
1GO_TAG=$(curl -s https://api.github.com/repos/grpc-ecosystem/grpc-gateway/releases/latest | jq -r .tag_name)
2wget https://github.com/grpc-ecosystem/grpc-gateway/releases/download/${GO_TAG}/protoc-gen-openapiv2-${GO_TAG}-linux-x86_64
3chmod +x protoc-gen-openapiv2-${GO_TAG}-linux-x86_64
4sudo mv protoc-gen-openapiv2-${GO_TAG}-linux-x86_64 /usr/local/bin/protoc-gen-openapiv2

b. Build dari Source

sh
1go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2@latest
Plugin akan berada di $GOPATH/bin.

Proses Generate Swagger/OpenAPI

Misalkan struktur folder seperti:

txt
1project/
2  ├── proto/
3  │   └── service.proto
4  └── gen/

Jalankan perintah berikut untuk generate file OpenAPI:

sh
1protoc -I proto/ \
2  --openapiv2_out=gen/ \
3  --openapiv2_opt logtostderr=true \
4  proto/service.proto

Setelah proses berjalan mulus, Anda akan mendapatkan file gen/service.swagger.json (atau .yaml jika diatur).

Simulasi Output (Potongan Swagger Spec)

json
 1{
 2  "swagger": "2.0",
 3  "info": {
 4    "title": "Greet API",
 5    "version": "1.0"
 6  },
 7  "paths": {
 8    "/v1/hello": {
 9      "post": {
10        "operationId": "SayHello",
11        "parameters": [
12          {
13            "name": "body",
14            "in": "body",
15            "schema": { "$ref": "#/definitions/greetHelloRequest" }
16          }
17        ],
18        "responses": {
19          "200": {
20            "description": "A successful response.",
21            "schema": { "$ref": "#/definitions/greetHelloReply" }
22          }
23        }
24      }
25    }
26  },
27  "definitions": {
28    "greetHelloRequest": {
29      "type": "object",
30      "properties": { "name": { "type": "string" } }
31    },
32    "greetHelloReply": {
33      "type": "object",
34      "properties": { "message": { "type": "string" } }
35    }
36  }
37}
Danger
Ini hanya potongan, file aslinya jauh lebih verbose.

Customisasi & Advanced Tips

1. REST Mapping

Agar endpoint REST bisa di-generate, atribut option (google.api.http) pada setiap rpc wajib ada. Jika tidak, path di Swagger/OpenAPI akan kosong.

2. Metadata Tambahan

Swagger memungkinkan penambahan info Title, Version, Contact, dsb:

proto
 1import "protoc-gen-openapiv2/options/annotations.proto";
 2
 3option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
 4  info: {
 5    title: "Greeter API";
 6    version: "1.0";
 7    contact: {
 8      name: "Tim API";
 9      email: "api@example.com";
10    }
11  }
12};

3. Multiple Proto File

Jika proyek Anda terdiri dari banyak file .proto, cukup daftarkan semua di perintah protoc, dan pastikan dependensi sesama file sudah terpasang sesuai import-nya.

Studi Simulasi: CI/CD Pipeline

Automasi terbaik biasanya di CI/CD pipeline. Berikut simulasi tahap di pipeline:

MERMAID
graph TB
    A[Push kode ke repo] --> B[Trigger CI]
    B --> C[Generate code dari .proto]
    C --> D[protoc-gen-openapiv2]
    D --> E[swagger.json artifact]
    E --> F{Deploy ke portal Dokumentasi?}
    F -- Ya --> G[Publish ke Swagger UI]
    F -- Tidak --> H[Simpan di artifact storage]

FAQ

Q: Apakah wajib menggunakan gRPC Gateway/REST server?
Tidak. Tujuan utama generate ini adalah memperoleh dokumentasi API. Namun, jika ingin service dapat diakses via HTTP/REST, perlu implementasi bridging dengan grpc-gateway.

Q: OpenAPI yang dihasilkan versi berapa?
Plugin protoc-gen-openapiv2 menghasilkan schema OpenAPI v2 (Swagger 2.0). Untuk OpenAPI v3, komunitas tengah mengembangkan plugin, silakan follow isu ini .

Q: Bisa custom response code?
Ya, dengan custom option pada file proto, tapi tidak selengkap Swagger manual.

Kesimpulan

Menggenerate dokumentasi Swagger/OpenAPI otomatis dari file Protobuf adalah solusi robust untuk menjaga konsistensi antara definisi API dan dokumentasinya. Dengan tool protoc-gen-openapiv2, proses ini bisa diintegrasikan ke workflow developer bahkan hingga ke CI/CD pipeline. Hasilnya? Developer happy, dokumentasi selalu up-to-date, dan kerja sama antar tim back-end dan front-end semakin solid.

Sudah saatnya buat dokumentasi API Anda berbicara langsung dari kode utama!

Referensi:

Artikel Terkait

💬 Komentar