protodoc

README

Protobuf API Documentation Generator CLI

This command-line interface (CLI) tool provides a simple way to generate API documentation in various formats (JSON, Markdown, YAML, HTML) from Protocol Buffer (Protobuf) files. It streamlines the documentation process for APIs defined using Protobuf, making it easier to understand and utilize your services.

Features

• Generate API documentation in JSON format.
• Generate API documentation in Markdown format.
• Generate API documentation in YAML format.
• Generate API documentation in HTML format.
• Support for Protobuf message and service definitions.
• Custom annotations for additional metadata (like paths and methods).

Installation

To install the Protobuf API Documentation Generator CLI, you can use the following command:

go install github.com/lovelyoyrmia/protodoc/cmd/protodoc@latest

Usage

Command-Line Interface

Once installed, you can use the protodoc command to generate documentation from your Protobuf files.

Basic Command

To generate documentation, run the following command:

protodoc --proto_dir=./proto --doc_opt=source_relative --type=json --doc_out=.

Options

• --proto_dir: Path to the Protobuf directory (can accept multiple files).
• --doc_opt: Documentation options for the generated documentation (source_relative).
• --doc_out: Output file path for the generated documentation.
• --type: Desired output format (json, markdown, yaml, html). Default type is markdown.
• --template_path: Path to the custom template file (need to has .tmpl extension).

Example Commands

1. Generate JSON Documentation

   protodoc --proto_dir=./proto --doc_opt=source_relative --type=json --doc_out=.
   

2. Generate Markdown Documentation

   protodoc --proto_dir=./proto --doc_opt=source_relative --doc_out=.
   

3. Generate YAML Documentation

   protodoc --proto_dir=./proto --doc_opt=source_relative --type=yaml --doc_out=.
   

4. Generate HTML Documentation

   protodoc --proto_dir=./proto --doc_opt=source_relative --type=html --doc_out=.
   

5. Generate Documentation with Custom Template

   protodoc --proto_dir=./proto --doc_opt=source_relative --type=html --doc_out=. --template_path=../custom_template.tmpl
   

API Options

The CLI supports custom API Options in your Protobuf files for additional metadata. Here’s how you can use them:

syntax = "proto3";

import "github.com/lovelyoyrmia/protodoc/options/options.proto";

package yourpackage;

// Service definition with annotations
service YourService {
    // Annotated RPC method
    rpc YourMethod (YourRequest) returns (YourResponse) {
        option (api_options) = {
            summary: ""
            path: "/myapi/mymethod"
            method: "POST"
            query_params: {
                name: "myid",
                type: "int",
                description: "mydescription",
                required: true,
            }
        };
    }
}

// Message definitions
message YourRequest {
    string id = 1; // Unique identifier
}

message YourResponse {
    string result = 1; // Result of the operation
}

Types

There are many data types used in the generated documentation. The table below summarizes the different types and their meanings.

Type	Description	Example
Common Types	Basic types like string, integer, etc.	string, int, etc.
Optional Types	Common types that are optional	string*, int*, etc.
Message Types	Custom Protobuf message types	#User, #Customer
Message Types (Optional)	Message types that are optional	#User*
List Types	Lists of common or message types	string[], int[], #User[]

Examples

For more examples you can see the examples folders.

Contribution

Contributions are welcome! If you have suggestions for improvements or new features, feel free to submit a pull request or open an issue. Please ensure to follow the Code of Conduct and the Contributing Guidelines.

License

This project is licensed under the MIT License. See the LICENSE file for more details.

Conclusion

The Protobuf API Documentation Generator CLI simplifies the process of generating API documentation from Protobuf files. With support for multiple formats and customizable annotations, you can ensure your API is well-documented and easily accessible.

For more information, check out the GitHub repository or reach out if you have any questions!

Documentation

Index

• Constants
• Variables
• func GenerateDescriptor(filename string) ([]*descriptorpb.FileDescriptorProto, error)
• type APIDoc
• type FieldDoc
• type IProtodoc
  • func (i *IProtodoc) GenerateAPIDoc() APIDoc
• type MessageDoc
• type MethodDoc
• type Option
  • func WithCustomTemplate(customTemplate string) Option
  • func WithDocOut(docOut string) Option
  • func WithFileDescriptor(fileDesc []*descriptorpb.FileDescriptorProto) Option
  • func WithName(name string) Option
  • func WithType(typeName ProtodocType) Option
• type Processor
• type Protodoc
  • func New(opts ...Option) Protodoc
  • func NewHTMLDoc(p *IProtodoc) Protodoc
  • func NewJsonDoc(p *IProtodoc) Protodoc
  • func NewMarkdownDoc(p *IProtodoc) Protodoc
  • func NewYamlDoc(p *IProtodoc) Protodoc
• type ProtodocType
  • func (p ProtodocType) ExtractExtension() string
  • func (p ProtodocType) Render() (Processor, error)
  • func (p ProtodocType) RenderCustom(inputTemplate string) Processor
  • func (p ProtodocType) String() string
• type QueryParameterDoc
• type ServiceDoc

Constants

const (
	DefaultApiDocName     = "API Documentation"
	DefaultApiDocsOut     = "."
	DefaultApiFileName    = "api-documentation"
	DefaultApiFileOut     = "api-documentation.md"
	DefaultDescriptorFile = "./api.desc"
)

const VERSION = "v1.2.2"

VERSION is the version of protodoc being used.

Variables

var ErrFileSetNotFound = errors.New("no files found in descriptor set")

Functions

func GenerateDescriptor

func GenerateDescriptor(filename string) ([]*descriptorpb.FileDescriptorProto, error)

GenerateDescriptor function to read descriptor file and returns all files descriptor proto

Types

type APIDoc

type APIDoc struct {
	// Name of the API Documentation.
	// This should be a descriptive title of the API, providing context to the users.
	Name string `json:"name" yaml:"name"`

	// Package represents the name of protobuf package
	Package string `json:"package" yaml:"package"`

	// GoPackage represents the name of protobuf go package
	GoPackage string `json:"go_package" yaml:"go_package"`

	// Author indicates the author of the API method documentation.
	Author string `json:"author" yaml:"author"`

	// BaseUrl is the root URL for the API, used to construct full endpoint URLs.
	BaseUrl string `json:"base_url" yaml:"base_url"`

	// Messages represent the request and response structures defined in Protobuf.
	// Each MessageDoc corresponds to a specific message type used in the API.
	Messages []MessageDoc `json:"messages" yaml:"messages"`

	// Services contains the API methods that can be invoked.
	// Each ServiceDoc corresponds to a specific service, detailing its methods.
	Services []ServiceDoc `json:"services" yaml:"services"`
}

APIDoc represents the overall API documentation structure.

type FieldDoc

type FieldDoc struct {
	// Name of the field.
	// This is the identifier for the field, as defined in the Protobuf message.
	Name string `json:"name" yaml:"name"`

	// Type of the field.
	// This specifies the data type of the field (e.g., string, int32, custom message).
	Type string `json:"type" yaml:"type"`
}

FieldDoc describes an individual field within a Protobuf message.

type IProtodoc

type IProtodoc struct {
	// Name of the API Documentation.
	// Default value is "API Documentation"
	Name string
	// Destination File is the path name of the API Documentation will be created.
	DestFile string
	// Type Name is the type documentation wants to be generated
	TypeName ProtodocType
	// Custom Template is the custom template for documentation
	CustomTemplate string

	FileDescriptors []*descriptorpb.FileDescriptorProto
}

func (*IProtodoc) GenerateAPIDoc

func (i *IProtodoc) GenerateAPIDoc() APIDoc

GenerateAPIDoc function to mapping file descriptors to API Documentation

type MessageDoc

type MessageDoc struct {
	// Name of the message type.
	// This is the identifier for the message, often matching the Protobuf definition.
	Name string `json:"name" name:"name"`

	// Fields represent the individual attributes within the message.
	// Each FieldDoc provides details about a specific field in the message.
	Fields []FieldDoc `json:"fields" yaml:"fields"`
}

MessageDoc describes a Protobuf message used in API requests or responses.

type MethodDoc

type MethodDoc struct {
	// Name of the method.
	// This is the identifier for the method, as defined in the Protobuf service.
	Name string `json:"name" yaml:"name"`

	// Summary provides a brief overview of what the method does.
	Summary string `json:"summary" yaml:"summary"`

	// Description offers a detailed explanation of the method's functionality and usage.
	Description string `json:"description" yaml:"description"`

	// Path is the API endpoint for the method, specifying how to access it.
	Path string `json:"path" yaml:"path"`

	// Method is the HTTP method (GET, POST, etc.) for the API call.
	Method string `json:"method" yaml:"method"`

	// InputType represents the expected input message type for the method.
	// This defines the structure of the data that the method will receive.
	// If the input type has an '@' prefix, it means it refers to an existing message type in the Protobuf schema.
	// The default message types are common types (string, int, etc).
	InputType string `json:"input_type" yaml:"input_type"`

	// OutputType represents the expected output message type for the method.
	// This defines the structure of the data that the method will return.
	// If the output type has an '@' prefix, it means it refers to an existing message type in the Protobuf schema.
	// The default message types are common types (string, int, etc).
	OutputType string `json:"output_type" yaml:"output_type"`

	// QueryParams represents a list of query parameters for the method.
	// Each parameter includes details such as name, type, description, and whether it is required.
	QueryParams []*QueryParameterDoc `json:"query_params" yaml:"query_params"`
}

MethodDoc describes an individual API method within a service.

type Option

type Option func(*IProtodoc)

func WithCustomTemplate

func WithCustomTemplate(customTemplate string) Option

WithCustomTemplate implements option the custom template want to be used

func WithDocOut

func WithDocOut(docOut string) Option

WithDocOut implements option out directory want to be generated

func WithFileDescriptor

func WithFileDescriptor(fileDesc []*descriptorpb.FileDescriptorProto) Option

WithFileDescriptor implements option file descriptor proto

func WithName

func WithName(name string) Option

WithName implements option name of API Documentation

func WithType

func WithType(typeName ProtodocType) Option

WithType implements option ProtodocType

type Processor

type Processor interface {
	Apply(apiDoc *APIDoc) ([]byte, error)
}

type Protodoc

type Protodoc interface {
	Generate() ([]byte, error)
	Execute() error
}

func New

func New(opts ...Option) Protodoc

func NewHTMLDoc

func NewHTMLDoc(p *IProtodoc) Protodoc

func NewJsonDoc

func NewJsonDoc(p *IProtodoc) Protodoc

func NewMarkdownDoc

func NewMarkdownDoc(p *IProtodoc) Protodoc

func NewYamlDoc

func NewYamlDoc(p *IProtodoc) Protodoc

type ProtodocType

type ProtodocType string

const (
	ProtodocTypeJson ProtodocType = "json"
	ProtodocTypeMD   ProtodocType = "markdown"
	ProtodocTypeYaml ProtodocType = "yaml"
	ProtodocTypeHTML ProtodocType = "html"
)

func (ProtodocType) ExtractExtension

func (p ProtodocType) ExtractExtension() string

func (ProtodocType) Render

func (p ProtodocType) Render() (Processor, error)

func (ProtodocType) RenderCustom

func (p ProtodocType) RenderCustom(inputTemplate string) Processor

func (ProtodocType) String

func (p ProtodocType) String() string

type QueryParameterDoc

type QueryParameterDoc struct {
	// Name of the query parameter.
	Name string `json:"name" yaml:"name"`

	// Type of the query parameter (e.g., string, int).
	Type string `json:"type" yaml:"type"`

	// Description of the query parameter.
	Description string `json:"description" yaml:"description"`

	// Indicates whether the query parameter is required.
	Required bool `json:"required" yaml:"required"`
}

QueryParameterDoc describes an individual query parameter for an API method.

type ServiceDoc

type ServiceDoc struct {
	// Name of the service.
	// This is the identifier for the service, often matching the Protobuf service name.
	Name string `json:"name" yaml:"name"`

	// Methods represent the individual API methods exposed by the service.
	// Each MethodDoc provides details about a specific method, including input and output types.
	Methods []MethodDoc `json:"methods" yaml:"methods"`
}

ServiceDoc represents a service that groups related API methods.