twirp-openapi-gen

Generate Open API V3 documentation for Twirp services

Installation

Binary

For installation instructions from binaries please visit the Releases Page.

Go

$  go install github.com/blockthrough/twirp-openapi-gen/cmd/twirp-openapi-gen@latest

Proto OpenAPI Mappings

Proto	OpenAPI
RPC	Path
Package.Service.RPC Name	Path.Key
RPC Name	Path.Summary
RPC Input	Path.RequestBody
RPC Output	Path.Response
RPC Comment	Path.Method.Description
RPC Req Example (comments with json objects prefixed by req-example)	Path.Method.RequestBody.Content.Content-Type.Example
RPC Res Example (comments with json objects prefixed by res-example)	Path.Method.Responses.200.Content.Content-Type.Example
Message	Component.Schema
Message Comment	Component.Schema.Description
Message Field	Component.Schema.Property
Message Field Comment	Component.Schema.Property.Description
Enum	Component.Schema.Property.Enum

Google Protobuf

The generator does a best effort attempt to map google.protobuf to OpenAPI types. The following table shows the mappings:

Google Protobuf	OpenAPI Type & Format
Timestamp	string & date-time
DateTime	string & date-time
Duration	string
StringValue	string
BytesValue	string & byte
Int32Value	integer & int32
UInt32Value	integer & uint32
Int64Value	string & int64
UInt64Value	string & uint64
FloatValue	number & float
DoubleValue	number & double
BoolValue	boolean
Empty	-
Any	object
ListValue	array
Struct	object
Value	string, number, integer, bolean, Struct or ListValue
google.type.Money	struct with currency_code, units and nanos

Notes

• The requestBody property of the path post operation only has one content-type of application/json, and its schema always references the RPC input message.
• Comments can be added above an RPC, message, or field resources. Inline comments are not supported.
• Path items only have one response with a 200 code using the schema of the message returned by the RPC method.
• All imports are resolved and their proto messages are added to the schema bucket. Only google/* proto imports are skipped.

Usage

❯ twirp-openapi-gen -h
Usage of twirp-openapi-gen:
  -format string
        Document format; json or yaml (default "json")
  -in value
        Input source .proto files. May be specified multiple times.
  -out string
        Output document file (default "./openapi-doc.json")
  -path-prefix string
        Twirp server path prefix (default "/twirp")
  -proto-path value
        Specify the directory in which to search for imports. May be specified multiple times; directories will be searched in order.  If not given, the current working directory is used.
  -servers value
        Server object URL. May be specified multiple times.
  -title string
        Document title (default "open-api-v3-docs")
  -verbose
        Log debug output
  -version string
        Document version

Examples

Generate OpenAPI V3 JSON document for the Twirp PetStore service:

❯ twirp-openapi-gen \
    -in ./internal/generator/testdata/petapis/pet/v1/pet.proto \
    -out ./internal/generator/testdata/pet-api-doc.json \
    -proto-path "$(shell realpath ./internal/generator/testdata/paymentapis/)" \
    -proto-path "$(shell realpath ./internal/generator/testdata/petapis/)" \
    -servers https://petapi.example.com \
    -path-prefix "" \
    -doc-version 1.0 \
    -title "Pet API"

Contributing

Makefile

Why

This project is a rewrite of the twirp-swagger-gen tool adding support to the latest OpenAPI v3 spec

Even though there are other ways of generating documentation for proto files, eg; protoc-gen-doc, gnostic, buf modules, etc. Neither provides an out-of the box solution to have interactive Twirp API docs.

There is already a rich ecosystem of tools for visualizing and interacting with OpenAPI V3 spec documents. The twirp-openapi-gen tool leverages that and generates valid JSON/YAML OpenAPI V3 documents from the proto definitions. The API docs can be imported to any tool that has support for OpenAPI V3, eg; Postman, Swagger, Stoplight, etc..