Feat: add service option (#6)

Author: kooksee

Makefile

@@ -15,3 +15,8 @@ pb_test:
 
 install_gnostic:
 	go install github.com/google/gnostic/cmd/[email protected]
+
+protobuf:
+	protobuild vendor
+	protobuild gen
+	rm -rf github.com

docs/_docs.go

@@ -0,0 +1,3 @@
+package docs
+
+// https://github.com/kollalabs/protoc-gen-openapi/tree/main

examples/tests/openapiv3annotations/message.proto

@@ -94,7 +94,37 @@ service Messaging1 {
 }
 
 service Messaging2 {
-    rpc UpdateMessage (Message) returns (Message) {}
+    rpc UpdateMessage (Message) returns (Message) {
+        option (openapi.v3.operation) = {
+            tags: ["abc=def"],
+            specification_extension: [
+                {
+                    name: "x-operation-id";
+                    value: {
+                        yaml: "updateMessage"
+                    };
+                }
+            ],
+            parameters: [{
+                parameter: {
+                    description: "jwt token",
+                    in: "header",
+                    name: "Authorization",
+                    required: true,
+                },
+            }],
+            security: [
+                {
+                    additional_properties: [
+                        {
+                            name: "BasicAuth";
+                            value: {}
+                        }
+                    ]
+                }
+            ]
+        };
+    }
 }
 
 message Message {

examples/tests/rpctypes/message.openapi.yaml

@@ -18,6 +18,7 @@ paths:
                         application/json:
                             schema:
                                 $ref: '#/components/schemas/Status'
+            x-folder: api/test
 components:
     schemas:
         GoogleProtobufAny:

examples/tests/rpctypes/message.proto

@@ -20,10 +20,18 @@ package tests.rpctypes.message.v1;
 import "google/protobuf/empty.proto";
 import "google/api/annotations.proto";
 import "google/rpc/status.proto";
+import "openapiv3/service.proto";
 
 option go_package = "github.com/google/gnostic/apps/protoc-gen-openapi/examples/tests/rpctypes/message/v1;message";
 
 service Status {
+  option(openapi.v3.service).specification_extension={
+    name: "x-folder"
+    value: {
+      yaml: "api/test"
+    }
+  };
+
   rpc GetStatus(google.protobuf.Empty) returns (google.rpc.Status) {
     option(google.api.http) = {
         get: "/v1/status"

generator/generator.go

@@ -25,14 +25,14 @@ import (
 
 	v3 "github.com/google/gnostic-models/openapiv3"
 	"google.golang.org/genproto/googleapis/api/annotations"
-	status_pb "google.golang.org/genproto/googleapis/rpc/status"
+	statuspb "google.golang.org/genproto/googleapis/rpc/status"
 	"google.golang.org/protobuf/compiler/protogen"
 	"google.golang.org/protobuf/proto"
 	"google.golang.org/protobuf/reflect/protoreflect"
 	"google.golang.org/protobuf/types/descriptorpb"
-	any_pb "google.golang.org/protobuf/types/known/anypb"
+	"google.golang.org/protobuf/types/known/anypb"
 
-	wk "github.com/pubgo/protoc-gen-openapi/generator/wellknown"
+	"github.com/pubgo/protoc-gen-openapi/generator/wellknown"
 )
 
 type Configuration struct {
@@ -55,8 +55,8 @@ const (
 // to know the message descriptors for google.rpc.Status as well
 // as google.protobuf.Any.
 var (
-	statusProtoDesc = (&status_pb.Status{}).ProtoReflect().Descriptor()
-	anyProtoDesc    = (&any_pb.Any{}).ProtoReflect().Descriptor()
+	statusProtoDesc = (&statuspb.Status{}).ProtoReflect().Descriptor()
+	anyProtoDesc    = (&anypb.Any{}).ProtoReflect().Descriptor()
 )
 
 // OpenAPIv3Generator holds internal state needed to generate an OpenAPIv3 document for a transcoded Protocol Buffer service.
@@ -122,15 +122,17 @@ func (g *OpenAPIv3Generator) buildDocumentV3() *v3.Document {
 	// track of which schemas are referenced in the response so we can
 	// add them later.
 	for _, file := range g.inputFiles {
-		if file.Generate {
-			// Merge any `Document` annotations with the current
-			extDocument := proto.GetExtension(file.Desc.Options(), v3.E_Document)
-			if extDocument != nil {
-				proto.Merge(d, extDocument.(*v3.Document))
-			}
+		if !file.Generate {
+			continue
+		}
 
-			g.addPathsToDocumentV3(d, file.Services)
+		// Merge any `Document` annotations with the current
+		extDocument := proto.GetExtension(file.Desc.Options(), v3.E_Document)
+		if extDocument != nil {
+			proto.Merge(d, extDocument.(*v3.Document))
 		}
+
+		g.addPathsToDocumentV3(d, file.Services)
 	}
 
 	// While we have required schemas left to generate, go through the files again
@@ -579,11 +581,11 @@ func (g *OpenAPIv3Generator) buildOperationV3(
 	// Add the default response if needed
 	if *g.conf.DefaultResponse {
 		anySchemaName := g.reflect.formatMessageName(anyProtoDesc)
-		anySchema := wk.NewGoogleProtobufAnySchema(anySchemaName)
+		anySchema := wellknown.NewGoogleProtobufAnySchema(anySchemaName)
 		g.addSchemaToDocumentV3(d, anySchema)
 
 		statusSchemaName := g.reflect.formatMessageName(statusProtoDesc)
-		statusSchema := wk.NewGoogleRpcStatusSchema(statusSchemaName, anySchemaName)
+		statusSchema := wellknown.NewGoogleRpcStatusSchema(statusSchemaName, anySchemaName)
 		g.addSchemaToDocumentV3(d, statusSchema)
 
 		defaultResponse := &v3.NamedResponseOrReference{
@@ -592,7 +594,7 @@ func (g *OpenAPIv3Generator) buildOperationV3(
 				Oneof: &v3.ResponseOrReference_Response{
 					Response: &v3.Response{
 						Description: "Default error response",
-						Content: wk.NewApplicationJsonMediaType(&v3.SchemaOrReference{
+						Content: wellknown.NewApplicationJsonMediaType(&v3.SchemaOrReference{
 							Oneof: &v3.SchemaOrReference_Reference{
 								Reference: &v3.Reference{XRef: "#/components/schemas/" + statusSchemaName},
 							},
@@ -705,8 +707,9 @@ func (g *OpenAPIv3Generator) addOperationToDocumentV3(d *v3.Document, op *v3.Ope
 // addPathsToDocumentV3 adds paths from a specified file descriptor.
 func (g *OpenAPIv3Generator) addPathsToDocumentV3(d *v3.Document, services []*protogen.Service) {
 	for _, service := range services {
-		annotationsCount := 0
+		extService, _ := proto.GetExtension(service.Desc.Options(), E_Service).(*Service)
 
+		annotationsCount := 0
 		for _, method := range service.Methods {
 			comment := g.filterCommentString(method.Comments.Leading)
 			inputMessage := method.Input
@@ -764,6 +767,18 @@ func (g *OpenAPIv3Generator) addPathsToDocumentV3(d *v3.Document, services []*pr
 						proto.Merge(op, extOperation.(*v3.Operation))
 					}
 
+					// Merge any `Service` annotations with the current
+					if extService != nil {
+						op.Parameters = append(op.Parameters, extService.Parameters...)
+						op.SpecificationExtension = append(op.SpecificationExtension, extService.SpecificationExtension...)
+						op.Tags = append(op.Tags, extService.Tags...)
+						op.Servers = append(op.Servers, extService.Servers...)
+						op.Security = append(op.Security, extService.Security...)
+						if extService.ExternalDocs != nil {
+							proto.Merge(op.ExternalDocs, extService.ExternalDocs)
+						}
+					}
+
 					for _, v := range op.Parameters {
 						if v.Oneof == nil {
 							continue
@@ -774,7 +789,7 @@ func (g *OpenAPIv3Generator) addPathsToDocumentV3(d *v3.Document, services []*pr
 							p := v1.Parameter
 							if p.In == "header" {
 								if p.Schema == nil {
-									p.Schema = wk.NewStringSchema()
+									p.Schema = wellknown.NewStringSchema()
 								}
 							}
 						}
@@ -840,15 +855,15 @@ func (g *OpenAPIv3Generator) addSchemasForMessagesToDocumentV3(d *v3.Document, m
 		// `google.protobuf.Value` and `google.protobuf.Any` have special JSON transcoding
 		// so we can't just reflect on the message descriptor.
 		if typeName == ".google.protobuf.Value" {
-			g.addSchemaToDocumentV3(d, wk.NewGoogleProtobufValueSchema(schemaName))
+			g.addSchemaToDocumentV3(d, wellknown.NewGoogleProtobufValueSchema(schemaName))
 			continue
 		} else if typeName == ".google.protobuf.Any" {
-			g.addSchemaToDocumentV3(d, wk.NewGoogleProtobufAnySchema(schemaName))
+			g.addSchemaToDocumentV3(d, wellknown.NewGoogleProtobufAnySchema(schemaName))
 			continue
 		} else if typeName == ".google.rpc.Status" {
 			anySchemaName := g.reflect.formatMessageName(anyProtoDesc)
-			g.addSchemaToDocumentV3(d, wk.NewGoogleProtobufAnySchema(anySchemaName))
-			g.addSchemaToDocumentV3(d, wk.NewGoogleRpcStatusSchema(schemaName, anySchemaName))
+			g.addSchemaToDocumentV3(d, wellknown.NewGoogleProtobufAnySchema(anySchemaName))
+			g.addSchemaToDocumentV3(d, wellknown.NewGoogleRpcStatusSchema(schemaName, anySchemaName))
 			continue
 		}
 

generator/reflector.go

@@ -23,7 +23,7 @@ import (
 	"google.golang.org/protobuf/compiler/protogen"
 	"google.golang.org/protobuf/reflect/protoreflect"
 
-	wk "github.com/pubgo/protoc-gen-openapi/generator/wellknown"
+	"github.com/pubgo/protoc-gen-openapi/generator/wellknown"
 )
 
 const (
@@ -90,10 +90,10 @@ func (r *OpenAPIv3Reflector) responseContentForMessage(message protoreflect.Mess
 	}
 
 	if typeName == ".google.api.HttpBody" {
-		return "200", wk.NewGoogleApiHttpBodyMediaType()
+		return "200", wellknown.NewGoogleApiHttpBodyMediaType()
 	}
 
-	return "200", wk.NewApplicationJsonMediaType(r.schemaOrReferenceForMessage(message))
+	return "200", wellknown.NewApplicationJsonMediaType(r.schemaOrReferenceForMessage(message))
 }
 
 func (r *OpenAPIv3Reflector) schemaReferenceForMessage(message protoreflect.MessageDescriptor) string {
@@ -110,44 +110,44 @@ func (r *OpenAPIv3Reflector) schemaOrReferenceForMessage(message protoreflect.Me
 	typeName := fullMessageTypeName(message)
 	switch typeName {
 	case ".google.api.HttpBody":
-		return wk.NewGoogleApiHttpBodySchema()
+		return wellknown.NewGoogleApiHttpBodySchema()
 
 	case ".google.protobuf.Timestamp":
-		return wk.NewGoogleProtobufTimestampSchema()
+		return wellknown.NewGoogleProtobufTimestampSchema()
 
 	case ".google.protobuf.Duration":
-		return wk.NewGoogleProtobufDurationSchema()
+		return wellknown.NewGoogleProtobufDurationSchema()
 
 	case ".google.type.Date":
-		return wk.NewGoogleTypeDateSchema()
+		return wellknown.NewGoogleTypeDateSchema()
 
 	case ".google.type.DateTime":
-		return wk.NewGoogleTypeDateTimeSchema()
+		return wellknown.NewGoogleTypeDateTimeSchema()
 
 	case ".google.protobuf.FieldMask":
-		return wk.NewGoogleProtobufFieldMaskSchema()
+		return wellknown.NewGoogleProtobufFieldMaskSchema()
 
 	case ".google.protobuf.Struct":
-		return wk.NewGoogleProtobufStructSchema()
+		return wellknown.NewGoogleProtobufStructSchema()
 
 	case ".google.protobuf.Empty":
 		// Empty is closer to JSON undefined than null, so ignore this field
 		return nil //&v3.SchemaOrReference{Oneof: &v3.SchemaOrReference_Schema{Schema: &v3.Schema{Type: "null"}}}
 
 	case ".google.protobuf.BoolValue":
-		return wk.NewBooleanSchema()
+		return wellknown.NewBooleanSchema()
 
 	case ".google.protobuf.BytesValue":
-		return wk.NewBytesSchema()
+		return wellknown.NewBytesSchema()
 
 	case ".google.protobuf.Int32Value", ".google.protobuf.UInt32Value":
-		return wk.NewIntegerSchema(getValueKind(message))
+		return wellknown.NewIntegerSchema(getValueKind(message))
 
 	case ".google.protobuf.StringValue", ".google.protobuf.Int64Value", ".google.protobuf.UInt64Value":
-		return wk.NewStringSchema()
+		return wellknown.NewStringSchema()
 
 	case ".google.protobuf.FloatValue", ".google.protobuf.DoubleValue":
-		return wk.NewNumberSchema(getValueKind(message))
+		return wellknown.NewNumberSchema(getValueKind(message))
 
 	default:
 		ref := r.schemaReferenceForMessage(message)
@@ -180,40 +180,40 @@ func (r *OpenAPIv3Reflector) schemaOrReferenceForField(field *protogen.Field, de
 			//
 			// So we need to find the `value` field in the `MapFieldEntry` message and
 			// then return a MapFieldEntry schema using the schema for the `value` field
-			return wk.NewGoogleProtobufMapFieldEntrySchema(r.schemaOrReferenceForField(field, desc.MapValue()))
+			return wellknown.NewGoogleProtobufMapFieldEntrySchema(r.schemaOrReferenceForField(field, desc.MapValue()))
 		} else {
 			kindSchema = r.schemaOrReferenceForMessage(desc.Message())
 		}
 
 	case protoreflect.StringKind:
-		kindSchema = wk.NewStringSchema()
+		kindSchema = wellknown.NewStringSchema()
 
 	case protoreflect.Int32Kind, protoreflect.Sint32Kind, protoreflect.Uint32Kind,
 		protoreflect.Sfixed32Kind, protoreflect.Fixed32Kind:
-		kindSchema = wk.NewIntegerSchema(kind.String())
+		kindSchema = wellknown.NewIntegerSchema(kind.String())
 
 	case protoreflect.Int64Kind, protoreflect.Sint64Kind, protoreflect.Uint64Kind,
 		protoreflect.Sfixed64Kind, protoreflect.Fixed64Kind:
-		kindSchema = wk.NewStringSchema()
+		kindSchema = wellknown.NewStringSchema()
 
 	case protoreflect.EnumKind:
-		kindSchema = wk.NewEnumSchema(r.conf.EnumType, field)
+		kindSchema = wellknown.NewEnumSchema(r.conf.EnumType, field)
 
 	case protoreflect.BoolKind:
-		kindSchema = wk.NewBooleanSchema()
+		kindSchema = wellknown.NewBooleanSchema()
 
 	case protoreflect.FloatKind, protoreflect.DoubleKind:
-		kindSchema = wk.NewNumberSchema(kind.String())
+		kindSchema = wellknown.NewNumberSchema(kind.String())
 
 	case protoreflect.BytesKind:
-		kindSchema = wk.NewBytesSchema()
+		kindSchema = wellknown.NewBytesSchema()
 
 	default:
 		log.Printf("(TODO) Unsupported field type: %+v", fullMessageTypeName(field.Desc.Message()))
 	}
 
 	if field.Desc.IsList() {
-		kindSchema = wk.NewListSchema(kindSchema)
+		kindSchema = wellknown.NewListSchema(kindSchema)
 	}
 
 	return kindSchema