Skip to content

easyp-tech/protoc-gen-easydoc

BranchesTags

Repository files navigation

protoc-gen-easydoc

Go License protobuf

A powerful documentation generator plugin for the Google Protocol Buffers compiler (protoc). Generate beautiful, interactive API documentation from your .proto files with full support for gRPC, grpc-gateway, validation rules, and custom annotations.

✨ Features

  • Multiple Output Formats — HTML, JSON, and Markdown
  • Interactive HTML — Search, tabs, copy buttons, syntax highlighting
  • gRPC Support — Services, methods, streaming (server/client/bidirectional)
  • REST API Support — Full grpc-gateway annotations (google.api.http)
  • Validation Rules — protoc-gen-validate integration
  • Field Behaviors — google.api.field_behavior support
  • Custom Annotations — Lightweight doc.v1 annotations for documentation
  • Auto-Generated Examples — Smart example generation based on field types and formats
  • Markdown in Comments — Headers, lists, tables, code blocks
  • Well-Known Types — Timestamp, Duration, FieldMask, Struct, and more

📦 Installation

Using Go

go install github.com/easyp-tech/protoc-gen-easydoc/cmd/protoc-gen-easydoc@latest

From Source

git clone https://github.com/easyp-tech/protoc-gen-easydoc.git
cd protoc-gen-easydoc
go build -o protoc-gen-easydoc ./cmd/protoc-gen-easydoc

🚀 Quick Start

Basic Usage

Generate HTML documentation (default):

protoc \
  --easydoc_out=./docs \
  -I . \
  your_service.proto

Generate specific formats:

protoc \
  --easydoc_out=./docs \
  --easydoc_opt=formats=html|json|md \
  -I . \
  your_service.proto

Using with easyp

Add to your easyp.yaml:

generate:
  plugins:
    - name: easydoc
      out: docs
      opts:
        formats: "html|json|md"

With source_relative paths (flat output):

generate:
  plugins:
    - name: easydoc
      out: docs
      opts:
        formats: "html|json|md"
        paths: "source_relative"

Then run:

easyp generate

📖 Writing Documentation

Service and Method Documentation

Document your services and methods using leading comments:

// UserService manages user accounts and authentication.
//
// ## Quick Start
//
// 1. Create a user: `POST /v1/users`
// 2. Authenticate: `POST /v1/auth/login`
// 3. Get profile: `GET /v1/users/{user_id}`
service UserService {
  // GetUser retrieves a user by their unique identifier.
  //
  // Returns `NOT_FOUND` if the user does not exist.
  rpc GetUser(GetUserRequest) returns (GetUserResponse) {
    option (google.api.http) = {
      get: "/v1/users/{user_id}"
    };
  }
}

Message and Field Documentation

// User represents a registered user in the system.
message User {
  // Unique identifier for the user.
  string id = 1;
  
  // User's email address, used for authentication.
  string email = 2;
  
  // Display name shown in the UI.
  string display_name = 3;
}

Markdown Support

Comments support rich Markdown formatting:

// # Authentication
//
// All endpoints require a Bearer token:
//
// ```
// Authorization: Bearer <token>
// ```
//
// ## Rate Limits
//
// | Endpoint | Limit |
// |----------|-------|
// | GET      | 1000/min |
// | POST     | 100/min |
//
// - Free tier: 1000 requests/day
// - Pro tier: unlimited

Excluding Comments

Prefix comments with @exclude to hide them from documentation:

// @exclude
// This is an internal implementation detail.
message InternalMessage {
  string id = 1; // @exclude internal field
}

🏷️ Annotations

doc.v1 Annotations

The plugin provides lightweight doc.v1 annotations for enhanced documentation without heavy dependencies:

import "doc/v1/doc.proto";

message CreateUserRequest {
  // User's unique identifier.
  string user_id = 1 [(doc.v1.field) = {
    required: true
    format: FORMAT_UUID
  }];

  // Email address for notifications.
  string email = 2 [(doc.v1.field) = {
    required: true
    format: FORMAT_EMAIL
    example: "john.doe@example.com"
  }];

  // User's age.
  int32 age = 3 [(doc.v1.field) = {
    min: 0
    max: 150
  }];

  // Username (3-32 lowercase alphanumeric characters).
  string username = 4 [(doc.v1.field) = {
    required: true
    min_length: 3
    max_length: 32
    pattern: "^[a-z][a-z0-9_-]*$"
  }];
}

Available Options

Option Type Description
required bool Mark field as required
output_only bool Field is read-only (set by server)
immutable bool Field can only be set on create
format Format Well-known format (see below)
custom_format string Custom format description
example string Example value (overrides auto-generation)
min / max double Numeric constraints
min_length / max_length int32 Length constraints
pattern string Regex pattern

Well-Known Formats

Format Example Description
FORMAT_UUID 550e8400-e29b-41d4-a716-446655440000 UUID v4
FORMAT_EMAIL user@example.com Email address
FORMAT_URI https://example.com/path URI/URL
FORMAT_HOSTNAME example.com Hostname
FORMAT_SLUG my-blog-post URL-friendly slug
FORMAT_DATE 1996-04-10 ISO 8601 date
FORMAT_DATE_TIME 1996-04-10T10:30:00Z ISO 8601 datetime
FORMAT_TIME 10:30:00 Time
FORMAT_DURATION 3600s Duration
FORMAT_IPV4 192.168.1.1 IPv4 address
FORMAT_IPV6 2001:db8::1 IPv6 address
FORMAT_MAC 00:1B:44:11:3A:B7 MAC address
FORMAT_CIDR 192.168.1.0/24 CIDR notation
FORMAT_PHONE +14155552671 E.164 phone number
FORMAT_CREDIT_CARD 4111111111111111 Credit card number
FORMAT_IBAN DE89370400440532013000 IBAN
FORMAT_BIC COBADEFFXXX BIC/SWIFT code
FORMAT_BYTE SGVsbG8gV29ybGQ= Base64 encoded
FORMAT_HEX 48656c6c6f Hexadecimal

protoc-gen-validate Integration

The plugin automatically extracts validation rules from protoc-gen-validate:

import "validate/validate.proto";

message CreatePetRequest {
  string name = 1 [(validate.rules).string = {
    min_len: 1
    max_len: 100
  }];

  string email = 2 [(validate.rules).string.email = true];

  int32 age = 3 [(validate.rules).int32 = {
    gte: 0
    lte: 30
  }];
}

google.api.field_behavior

Field behaviors are also supported:

import "google/api/field_behavior.proto";

message Pet {
  string id = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
  string name = 2 [(google.api.field_behavior) = REQUIRED];
}

🌐 HTTP/REST Annotations

Full support for grpc-gateway annotations:

import "google/api/annotations.proto";

service PetService {
  // Create a new pet.
  rpc CreatePet(CreatePetRequest) returns (Pet) {
    option (google.api.http) = {
      post: "/v1/pets"
      body: "pet"
    };
  }

  // Update an existing pet.
  rpc UpdatePet(UpdatePetRequest) returns (Pet) {
    option (google.api.http) = {
      patch: "/v1/pets/{pet_id}"
      body: "pet"
      additional_bindings {
        put: "/v1/pets/{pet_id}"
        body: "*"
      }
    };
  }

  // Search for pets.
  rpc SearchPets(SearchPetsRequest) returns (SearchPetsResponse) {
    option (google.api.http) = {
      get: "/v1/pets:search"
    };
  }
}

📊 Streaming RPCs

Document all streaming patterns:

service PetService {
  // Server streaming: Watch for pet updates.
  rpc WatchPets(WatchPetsRequest) returns (stream PetEvent);

  // Client streaming: Batch create pets.
  rpc BatchCreatePets(stream CreatePetRequest) returns (BatchCreatePetsResponse);

  // Bidirectional streaming: Sync pets.
  rpc SyncPets(stream PetSyncRequest) returns (stream PetSyncResponse);
}

📤 Output Formats

HTML

Interactive documentation with:

  • 🔍 Full-text search
  • 📑 Protocol tabs (gRPC / HTTP)
  • 📋 Copy buttons for examples
  • 🎨 Syntax highlighting
  • 📱 Responsive design
  • 🧭 Collapsible navigation

JSON

Machine-readable output for integrations:

{
  "file": "petstore.proto",
  "package": "petstore.v1",
  "services": [...],
  "messages": [...],
  "enums": [...]
}

Markdown

GitHub/GitLab-friendly documentation suitable for wikis and README files.

📁 Examples

The examples/ directory contains comprehensive examples:

File Description
petstore.proto Full-featured API with REST, gRPC, streaming, validation
with_doc_annotations.proto Examples of doc.v1 annotations

Generate Example Documentation

cd examples
protoc \
  --easydoc_out=. \
  --easydoc_opt=formats=html|json|md \
  -I . \
  -I /path/to/googleapis \
  -I /path/to/protoc-gen-validate \
  petstore.proto

🔧 Configuration

Command Line Options

Option Default Description
formats html Output formats separated by | (pipe)
paths (empty) Output path mode: source_relative or empty for default

Available formats: html, json, md

Output Path Modes

Mode Description Example
(default) Preserves input directory structure api/v1/pet.proto → docs/api/v1/pet.html
source_relative Outputs only filename, no directories api/v1/pet.proto → docs/pet.html

Examples

Default mode (preserves directory structure):

protoc \
  --easydoc_out=./docs \
  --easydoc_opt=formats=html|json|md \
  -I . \
  api/v1/*.proto

Source-relative mode (flat output):

protoc \
  --easydoc_out=./docs \
  --easydoc_opt=paths=source_relative,formats=html|json|md \
  -I . \
  api/v1/*.proto

🤝 Example Generation Priority

Examples are automatically generated with the following priority:

  1. Explicit doc.v1.field.example — User-defined example
  2. doc.v1.field.format — Generated from format (UUID, email, etc.)
  3. validate.rules — Generated from validation rules
  4. Default by type — Sensible defaults for scalar types

📋 Supported Features

Field Types

  • ✅ Scalars: string, int32, int64, uint32, uint64, float, double, bool, bytes
  • ✅ Messages (nested and referenced)
  • ✅ Enums (top-level and nested)
  • ✅ Maps: map<K, V>
  • ✅ Repeated fields
  • ✅ Oneofs
  • ✅ Well-known types: Timestamp, Duration, FieldMask, Struct, Empty, Any

Documentation

  • ✅ Leading comments
  • ✅ Trailing comments
  • ✅ @exclude directive
  • ✅ Markdown formatting
  • ✅ Deprecation notices
  • ✅ Reserved fields/values

📄 License

Apache License 2.0 — see LICENSE for details.

🙏 Acknowledgments

Inspired by protoc-gen-doc with enhanced features for modern API documentation needs.

Made with ❤️ by easyp-tech

About

No description, website, or topics provided.

Resources

Readme

License

Apache-2.0 license
Activity
Custom properties

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

4 tags

Packages

 
 
 

Contributors

Languages