protoc-gen-openapi

protoc-gen-openapi

Contains a protoc plugin that generates openapi v3 documents

Forked from github.com/google/gnostic/cmd/protoc-gen-openapi

Installation:

go install github.com/lee20h/protoc-gen-openapi@latest

Usage:

protoc sample.proto -I. --openapi_out=version=1.2.3:.

Testing

To see output during tests use log.Print*

go clean -testcache && go test

Added Features

We have added some features that the Gnostic team most likely doesn't want to add :-) Some are fairly Kolla specific, sorry. We try to hide Kolla specific functionality in a way that won't trip anyone up.

• Better Enum Support
• Summary Field
• Validation (protoc-gen-validate)
• Google Field Behavior Annotations
• OAS3 header support
• Default Headers
• Protobuf Version
• Multiple Servers
• Output Mode (merged/source_relative)

Better Enum Support

Enums work better by using string values of proto enums instead of ints.

Summary Field

Sometimes you want more control over certain properties in the OpenAPI manifest. In our case we wanted to use the summary property on routes to look nice for generating documentation from the OpenAPI manifest. Normally the summary comes simply from the name of the route. We added a feature that parses the comment over the proto service method and looks for a pipe character ("|") and if it sees it, it will take anything to the left of it and put it in the summary field, and anything to the right of it will be the description. If no pipe is found it puts the whole comment in the description like normal. From /examples/tests/summary/message.proto:

service Messaging {
    // Update Message Summary | This function updates a message.
    rpc UpdateMessage(Message) returns(Message) {
        option(google.api.http) = {
            patch: "/v1/messages/{message_id}"
            body: "text"
        };
    }
}

It generates the following OpenAPI:

#...
paths:
    /v1/messages/{message_id}:
        patch:
            tags:
                - Messaging
            summary: Update Message Summary # Look at this beautiful summary...
            description: This function updates a message.
#...

Validation

We added partial support for protoc-gen-validate annotations

OpenAPI spec allows for a small handful of input validation configurations. Proto has an awesome plugin called protoc-gen-validate for generating validation code in Go, Java, C++, etc. We took those same annotations and added support in this project for them.

Usage: add validate=true to protoc command.

protoc sample.proto -I. --openapi_out=version=1.2.3,validate=true:.

Example

message Message {
    string message_id = 1;
    string text = 2 [(validate.rules)= {
        string: {
            uri:true,
            max_len:45,
            min_len:1
        }
    }];
    int64 mynum = 3 [(validate.rules).int64 = {gte:1, lte:30}];
}

outputs:

components:
    schemas:
        Message:
            properties:
                message_id:
                    type: string
                text:
                    maxLength: 45
                    minLength: 1
                    type: string
                    format: uri
                mynum:
                    maximum: !!float 30
                    minimum: !!float 1
                    type: integer
                    format: int64

Supported Validators

String

• uri
• uuid
• email
• ipv4
• ipv6
• max_len
• min_len

Int32

• gte
• lte

Int64

• gte
• lte

Adding more can easily be done in the function addValidationRules in /generator/openapi-v3.yaml

Google Field Behavior Annotations

• (google.api.field_behavior) = REQUIRED will add the field to the required list in the openAPI schema
• (google.api.field_behavior) = OUTPUT_ONLY will add the readOnly property to the field
• (google.api.field_behavior) = INPUT_ONLY will add the writeOnly property to the field
• TODO: (google.api.field_behavior) = IMMUTABLE will add the x-createOnly property to the field (not supported by openapi yet)

OAS3 header support

Default Headers

service LibraryService {

  option (openapi.service_params) = {
    headers: [
      {
        name:"Authorization",
        pattern:"^(.*)$"
        description:"This is authorization header"
        required:true
        default:{
          string:"Bearer abc123"
        }
      },
      {
        name:"x-custom-default-header",
        pattern:"^(.*)$"
        description:"This is request protocol header"
        required:true
        default:{
          string:"default_value"
        }
      }
    ]
  };
}

output:

            parameters:
                - name: Authorization
                  in: header
                  description: This is authorization header
                  required: true
                  schema:
                    pattern: ^(.*)$
                    type: string
                    default: Bearer abc123
                - name: x-custom-default-header
                  in: header
                  description: This is request protocol header
                  required: true
                  schema:
                    pattern: ^(.*)$
                    type: string
                    default: default_value

Protobuf Version & Multple Servers

option (google.api.version) = "1.0.0";
option (google.api.default_host) = "app.example.com";
option (google.api.default_host) = "app2.example.com";

output:

info:
    version: 1.0.0
servers:
  - url: app.example.com
  - url: app2.example.com

Output Mode ( merged / source_relative )

protoc sample.proto -I. --openapi_out=output_mode=source_relative:.

Converts each protobuf file to an openAPI Spec file according to yaml/json format. In the case of merged, it combines the contents of all protobufs to convert them into a single openAPI Spec file