72. Generate Swagger/OpenAPI dari Protobuf

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:

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:

// service.proto
syntax = "proto3";

package greet;

service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply) {
    option (google.api.http) = {
      post: "/v1/hello"
      body: "*"
    };
  }
}

message HelloRequest {
  string name = 1;
}

message HelloReply {
  string message = 1;
}

Catatan: Option (google.api.http) penting untuk mapping endpoint gRPC ke REST.

Toolchain yang Dibutuhkan

Instalasi plugin: protoc-gen-openapiv2

Cara Instalasi

a. Download Binary (Rekomendasi di CI/CD)

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

b. Build dari Source

go 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:

project/
  ├── proto/
  │   └── service.proto
  └── gen/

Jalankan perintah berikut untuk generate file OpenAPI:

protoc -I proto/ \
  --openapiv2_out=gen/ \
  --openapiv2_opt logtostderr=true \
  proto/service.proto

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

Simulasi Output (Potongan Swagger Spec)

{
  "swagger": "2.0",
  "info": {
    "title": "Greet API",
    "version": "1.0"
  },
  "paths": {
    "/v1/hello": {
      "post": {
        "operationId": "SayHello",
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "schema": { "$ref": "#/definitions/greetHelloRequest" }
          }
        ],
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": { "$ref": "#/definitions/greetHelloReply" }
          }
        }
      }
    }
  },
  "definitions": {
    "greetHelloRequest": {
      "type": "object",
      "properties": { "name": { "type": "string" } }
    },
    "greetHelloReply": {
      "type": "object",
      "properties": { "message": { "type": "string" } }
    }
  }
}

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:

import "protoc-gen-openapiv2/options/annotations.proto";

option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
  info: {
    title: "Greeter API";
    version: "1.0";
    contact: {
      name: "Tim API";
      email: "api@example.com";
    }
  }
};

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:

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:

• grpc-ecosystem/grpc-gateway
• OpenAPI Specification
• Protocol Buffers