Automate Go gRPC API Docs in 3 Steps: Swagger Integration & Live Debugging

Why Automate API Documentation?

In microservice architectures, API documentation must stay accurate and up‑to‑date to avoid synchronization issues, high maintenance cost, and low debugging efficiency.

Docs can fall out of sync with code after interface changes.

Manual alignment of Proto definitions and Swagger specs incurs high maintenance cost.

Lack of an interactive testing tool reduces debugging efficiency.

Technology Choice: Swagger

Swagger can generate documentation directly from .proto files, provides an interactive UI for testing, supports both gRPC and REST, and keeps documentation versioned with code changes.

Tech Stack

Proto3 : Interface definition language.

Buf : Modern Protobuf build tool that replaces repetitive protoc commands.

grpc-gateway : Generates a reverse‑proxy translating gRPC calls to HTTP/REST.

Swagger UI : Web UI that renders OpenAPI specifications and allows interactive calls.

Project Walkthrough

3.1 Environment Setup

# Install Buf
brew install bufbuild/buf/buf   # macOS
# Or use the official script
curl -sSL https://buf.build/install | bash

# Install required Go plugins
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2@latest

3.2 Proto File Annotation Guidelines

Example search.proto:

syntax = "proto3";
package search;

import "google/api/annotations.proto";

option go_package = "github.com/yourproject/protos/services";

service SearchService {
  rpc SearchPart (SearchRequest) returns (SearchResponse) {
    option (google.api.http) = {
      post: "/v1/search/part"
      body: "*"
    };
  }
}

message SearchRequest {
  string query = 1 [
    (google.api.field_behavior) = REQUIRED,
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      description: "搜索关键词",
      min_length: 2,
      example: "CPU"
    }
  ];
}

message SearchResponse {
  repeated Part parts = 1;
}

message Part {
  string id = 1;
  string name = 2;
}

3.3 Generating Swagger Documentation with Buf

3.3.1 Initialize Buf Configuration

buf init

Create a buf.yaml file with the following content:

version: v1

deps:
  - buf.build/googleapis/googleapis
  - buf.build/grpc-ecosystem/grpc-gateway

breaking:
  use:
    - FILE

lint:
  use:
    - DEFAULT

generate:
  openapiv2:
    out: gen/openapi
    opt:
      json_names_for_fields: false
      allow_merge: true

3.3.2 Execute Documentation Generation

buf generate

The command produces OpenAPI v2 JSON/YAML files under gen/openapi, which can be served directly to Swagger UI.

3.4 Deploying Swagger UI

3.4.1 Minimal Go Server

package main

import (
    "log"
    "net/http"

    "github.com/gorilla/mux"
    httpSwagger "github.com/swaggo/http-swagger"
)

func main() {
    r := mux.NewRouter()
    r.PathPrefix("/swagger/").Handler(httpSwagger.WrapHandler)
    log.Fatal(http.ListenAndServe(":8080", r))
}

Running this program serves the generated OpenAPI specification at http://localhost:8080/swagger/, providing an interactive interface for testing the gRPC‑to‑REST endpoints.