twopdocs

README

Twirp OpenAPI 3 Docs

Generates OpenAPI 3 documentation from Twirp protobuf declarations.

Usage

Makefile example

bin_dir=$(shell pwd)/bin
service=directory
proto_plugins=bin/protoc-gen-openapi3
generated_files=directory-openapi.json
version=v1.0.0

bin/protoc-gen-openapi3: go.mod $(wildcard *.go) cmd/protoc-gen-openapi3/main.go
	GOBIN=$(bin_dir) go install ./cmd/protoc-gen-openapi3

.PHONY: generate
generate: $(service)-openapi.json

$(service)-openapi.json: rpc/$(service)/service.proto $(proto_plugins)
	PATH=$(bin_dir):$(PATH) protoc \
	--proto_path=. \
	--openapi3_out=. --openapi3_opt=application=$(service),version=$(version) \
	rpc/$(service)/service.proto

When used in another package installation can be handled like this:

bin/protoc-gen-twirp: go.mod
	GOBIN=$(bin_dir) go install github.com/twitchtv/twirp/protoc-gen-twirp

...if you have specified twopdocs as a "tools.go" dependency:

//go:build tools
// +build tools

package yourpackage

import (
	_ "github.com/navigacontentlab/twopdocs"
)

Documentation

Index

• func GoogleTimestamp(f MessageField) (*openapi3.SchemaRef, error)
• func NavigaSaasServer(application string, infomaker bool) *openapi3.Server
• func ToOpenAPI(application string, version string, d Doc, _ *protogen.Plugin, ...) (openapi3.T, error)
• type CustomFieldFunc
• type Doc
  • func StructureDump(gen *protogen.Plugin) Doc
• type Enum
• type EnumValue
• type File
• type Message
• type MessageField
• type Method
• type SchemaGenerator
  • func NewSchemaGenerator(doc Doc) *SchemaGenerator
  • func (sg *SchemaGenerator) EnumSchema(e Enum) (*openapi3.SchemaRef, error)
  • func (sg *SchemaGenerator) MessageSchema(typeName string) (*openapi3.SchemaRef, error)
• type Service

Functions

func GoogleTimestamp

func GoogleTimestamp(f MessageField) (*openapi3.SchemaRef, error)

func NavigaSaasServer

func NavigaSaasServer(application string, infomaker bool) *openapi3.Server

func ToOpenAPI

func ToOpenAPI(
	application string, version string, d Doc,
	_ *protogen.Plugin, schemaGen *SchemaGenerator,
) (openapi3.T, error)

Types

type CustomFieldFunc

type CustomFieldFunc func(f MessageField) (*openapi3.SchemaRef, error)

type Doc

type Doc struct {
	Files []File `json:"files"`
}

func StructureDump

func StructureDump(gen *protogen.Plugin) Doc

type Enum

type Enum struct {
	Name        string      `json:"name"`
	FullName    string      `json:"fullName"`
	Description string      `json:"description"`
	Values      []EnumValue `json:"values"`
}

type EnumValue

type EnumValue struct {
	Name        string `json:"name"`
	Number      string `json:"number"`
	Description string `json:"description"`
}

type File

type File struct {
	Name        string    `json:"name"`
	Description string    `json:"description"`
	Services    []Service `json:"services"`
	Messages    []Message `json:"messages"`
	Enums       []Enum    `json:"enums"`
}

type Message

type Message struct {
	Name        string         `json:"name"`
	FullName    string         `json:"fullName"`
	Description string         `json:"description"`
	Fields      []MessageField `json:"fields"`
}

type MessageField

type MessageField struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	Type        string `json:"type"`
	FullType    string `json:"fullType"`
	IsRepeated  bool   `json:"isRepeated,omitempty"`
	IsMap       bool   `json:"isMap"`
	IsRequired  bool   `json:"isRequired"`
	MapKey      string `json:"mapKey,omitempty"`
	MapValue    string `json:"mapValue,omitempty"`
}

type Method

type Method struct {
	Name         string `json:"name"`
	Description  string `json:"description"`
	RequestType  string `json:"requestType"`
	ResponseType string `json:"responseType"`
}

type SchemaGenerator

type SchemaGenerator struct {
	CustomFields map[string]CustomFieldFunc
	// contains filtered or unexported fields
}

func NewSchemaGenerator

func NewSchemaGenerator(doc Doc) *SchemaGenerator

func (*SchemaGenerator) EnumSchema

func (sg *SchemaGenerator) EnumSchema(e Enum) (*openapi3.SchemaRef, error)

func (*SchemaGenerator) MessageSchema

func (sg *SchemaGenerator) MessageSchema(typeName string) (*openapi3.SchemaRef, error)

type Service

type Service struct {
	Name        string   `json:"name"`
	FullName    string   `json:"fullName"`
	Description string   `json:"description"`
	Methods     []Method `json:"methods"`
}