add support for file/document and method/operation annotations. fixes g…

…oogle#308
jeffsawatzky · Mar 28, 2022 · 73b03aa · 73b03aa
1 parent 15e2bfb
commit 73b03aa
Show file tree

Hide file tree

Showing 11 changed files with 524 additions and 1 deletion.
diff --git a/COMPILE-PROTOS.sh b/COMPILE-PROTOS.sh
@@ -19,6 +19,7 @@ go install github.com/golang/protobuf/protoc-gen-go@latest
 
 protoc -I . -I ./third_party --go_out=. openapiv2/OpenAPIv2.proto
 protoc -I . -I ./third_party --go_out=. openapiv3/OpenAPIv3.proto
+protoc -I . -I ./third_party --go_out=. openapiv3/annotations.proto
 protoc -I . -I ./third_party --go_out=. discovery/discovery.proto
 protoc -I . -I ./third_party --go_out=. plugins/plugin.proto
 protoc -I . -I ./third_party --go_out=. extensions/extension.proto

diff --git a/cmd/protoc-gen-openapi/examples/tests/openapiv3annotations/message.proto b/cmd/protoc-gen-openapi/examples/tests/openapiv3annotations/message.proto
@@ -0,0 +1,87 @@
+// Copyright 2021 Google LLC.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+syntax = "proto3";
+
+package tests.mapfields.message.v1;
+
+import "google/api/annotations.proto";
+import "openapiv3/annotations.proto";
+
+option go_package = "github.com/google/gnostic/apps/protoc-gen-openapi/examples/tests/noannotations/message/v1;message";
+
+option (openapi.v3.document) = {
+  info: {
+    title: "Title from annotation";
+    version: "Version from annotation";
+    description: "Description from annotation";
+    contact: {
+      name: "Contact Name";
+      url: "https://github.com/google/gnostic";
+      email: "[email protected]";
+    }
+    license: {
+      name: "Apache License";
+      url: "https://github.com/google/gnostic/blob/master/LICENSE";
+    }
+  }
+  components: {
+    security_schemes: {
+      additional_properties: [
+        {
+          name: "BasicAuth";
+          value: {
+            security_scheme: {
+              type: "http";
+              scheme: "basic";
+            }
+          }
+        }
+      ]
+    }
+  }
+};
+
+service Messaging1 {
+  rpc UpdateMessage(Message) returns(Message) {
+    option(google.api.http) = {
+        patch: "/v1/messages/{message_id}"
+        body: "*"
+    };
+    option(openapi.v3.operation) = {
+        security: [
+          {
+            additional_properties: [
+              {
+                name: "BasicAuth";
+                value: {
+                  value: []
+                }
+              }
+            ]
+          }
+        ]
+    };
+  }
+}
+
+service Messaging2 {
+  rpc UpdateMessage(Message) returns (Message) {}
+}
+
+message Message {
+  int64 id = 1;
+  string label = 2;
+}
diff --git a/cmd/protoc-gen-openapi/examples/tests/openapiv3annotations/openapi.yaml b/cmd/protoc-gen-openapi/examples/tests/openapiv3annotations/openapi.yaml
@@ -0,0 +1,58 @@
+# Generated with protoc-gen-openapi
+# https://github.com/google/gnostic/tree/master/cmd/protoc-gen-openapi
+
+openapi: 3.0.3
+info:
+    title: Title from annotation
+    description: Description from annotation
+    contact:
+        name: Contact Name
+        url: https://github.com/google/gnostic
+        email: [email protected]
+    license:
+        name: Apache License
+        url: https://github.com/google/gnostic/blob/master/LICENSE
+    version: Version from annotation
+paths:
+    /v1/messages/{message_id}:
+        patch:
+            tags:
+                - Messaging1
+            operationId: Messaging1_UpdateMessage
+            parameters:
+                - name: message_id
+                  in: path
+                  required: true
+                  schema:
+                    type: string
+            requestBody:
+                content:
+                    application/json:
+                        schema:
+                            $ref: '#/components/schemas/Message'
+                required: true
+            responses:
+                "200":
+                    description: OK
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/Message'
+            security:
+                - BasicAuth: []
+components:
+    schemas:
+        Message:
+            type: object
+            properties:
+                id:
+                    type: integer
+                    format: int64
+                label:
+                    type: string
+    securitySchemes:
+        BasicAuth:
+            type: http
+            scheme: basic
+tags:
+    - name: Messaging1
diff --git a/cmd/protoc-gen-openapi/examples/tests/openapiv3annotations/openapi_fq_schema_naming.yaml b/cmd/protoc-gen-openapi/examples/tests/openapiv3annotations/openapi_fq_schema_naming.yaml
@@ -0,0 +1,58 @@
+# Generated with protoc-gen-openapi
+# https://github.com/google/gnostic/tree/master/cmd/protoc-gen-openapi
+
+openapi: 3.0.3
+info:
+    title: Title from annotation
+    description: Description from annotation
+    contact:
+        name: Contact Name
+        url: https://github.com/google/gnostic
+        email: [email protected]
+    license:
+        name: Apache License
+        url: https://github.com/google/gnostic/blob/master/LICENSE
+    version: Version from annotation
+paths:
+    /v1/messages/{message_id}:
+        patch:
+            tags:
+                - Messaging1
+            operationId: Messaging1_UpdateMessage
+            parameters:
+                - name: message_id
+                  in: path
+                  required: true
+                  schema:
+                    type: string
+            requestBody:
+                content:
+                    application/json:
+                        schema:
+                            $ref: '#/components/schemas/tests.mapfields.message.v1.Message'
+                required: true
+            responses:
+                "200":
+                    description: OK
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/tests.mapfields.message.v1.Message'
+            security:
+                - BasicAuth: []
+components:
+    schemas:
+        tests.mapfields.message.v1.Message:
+            type: object
+            properties:
+                id:
+                    type: integer
+                    format: int64
+                label:
+                    type: string
+    securitySchemes:
+        BasicAuth:
+            type: http
+            scheme: basic
+tags:
+    - name: Messaging1
diff --git a/cmd/protoc-gen-openapi/examples/tests/openapiv3annotations/openapi_json.yaml b/cmd/protoc-gen-openapi/examples/tests/openapiv3annotations/openapi_json.yaml
@@ -0,0 +1,58 @@
+# Generated with protoc-gen-openapi
+# https://github.com/google/gnostic/tree/master/cmd/protoc-gen-openapi
+
+openapi: 3.0.3
+info:
+    title: Title from annotation
+    description: Description from annotation
+    contact:
+        name: Contact Name
+        url: https://github.com/google/gnostic
+        email: [email protected]
+    license:
+        name: Apache License
+        url: https://github.com/google/gnostic/blob/master/LICENSE
+    version: Version from annotation
+paths:
+    /v1/messages/{message_id}:
+        patch:
+            tags:
+                - Messaging1
+            operationId: Messaging1_UpdateMessage
+            parameters:
+                - name: message_id
+                  in: path
+                  required: true
+                  schema:
+                    type: string
+            requestBody:
+                content:
+                    application/json:
+                        schema:
+                            $ref: '#/components/schemas/Message'
+                required: true
+            responses:
+                "200":
+                    description: OK
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/Message'
+            security:
+                - BasicAuth: []
+components:
+    schemas:
+        Message:
+            type: object
+            properties:
+                id:
+                    type: integer
+                    format: int64
+                label:
+                    type: string
+    securitySchemes:
+        BasicAuth:
+            type: http
+            scheme: basic
+tags:
+    - name: Messaging1
diff --git a/cmd/protoc-gen-openapi/examples/tests/openapiv3annotations/openapi_string_enum.yaml b/cmd/protoc-gen-openapi/examples/tests/openapiv3annotations/openapi_string_enum.yaml
@@ -0,0 +1,58 @@
+# Generated with protoc-gen-openapi
+# https://github.com/google/gnostic/tree/master/cmd/protoc-gen-openapi
+
+openapi: 3.0.3
+info:
+    title: Title from annotation
+    description: Description from annotation
+    contact:
+        name: Contact Name
+        url: https://github.com/google/gnostic
+        email: [email protected]
+    license:
+        name: Apache License
+        url: https://github.com/google/gnostic/blob/master/LICENSE
+    version: Version from annotation
+paths:
+    /v1/messages/{message_id}:
+        patch:
+            tags:
+                - Messaging1
+            operationId: Messaging1_UpdateMessage
+            parameters:
+                - name: message_id
+                  in: path
+                  required: true
+                  schema:
+                    type: string
+            requestBody:
+                content:
+                    application/json:
+                        schema:
+                            $ref: '#/components/schemas/Message'
+                required: true
+            responses:
+                "200":
+                    description: OK
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/Message'
+            security:
+                - BasicAuth: []
+components:
+    schemas:
+        Message:
+            type: object
+            properties:
+                id:
+                    type: integer
+                    format: int64
+                label:
+                    type: string
+    securitySchemes:
+        BasicAuth:
+            type: http
+            scheme: basic
+tags:
+    - name: Messaging1
diff --git a/cmd/protoc-gen-openapi/generator/openapi-v3.go b/cmd/protoc-gen-openapi/generator/openapi-v3.go
@@ -104,6 +104,12 @@ func (g *OpenAPIv3Generator) buildDocumentV3() *v3.Document {
 
 	for _, file := range g.plugin.Files {
 		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))
+			}
+
 			g.addPathsToDocumentV3(d, file)
 		}
 	}
@@ -278,6 +284,13 @@ func (g *OpenAPIv3Generator) addPathsToDocumentV3(d *v3.Document, file *protogen
 
 				op, path2 := g.buildOperationV3(
 					file, operationID, service.GoName, comment, defaultHost, path, body, inputMessage, outputMessage)
+
+				// Merge any `Operation` annotations with the current
+				extOperation := proto.GetExtension(method.Desc.Options(), v3.E_Operation)
+				if extOperation != nil {
+					proto.Merge(op, extOperation.(*v3.Operation))
+				}
+
 				g.addOperationV3(d, op, path2, methodName)
 			}
 		}

diff --git a/cmd/protoc-gen-openapi/main.go b/cmd/protoc-gen-openapi/main.go
@@ -41,7 +41,7 @@ func main() {
 	}
 
 	opts.Run(func(plugin *protogen.Plugin) error {
-		// Enable "optional" keyword in front of type (e.g. optional string labe = 1;)
+		// Enable "optional" keyword in front of type (e.g. optional string label = 1;)
 		plugin.SupportedFeatures = uint64(pluginpb.CodeGeneratorResponse_FEATURE_PROTO3_OPTIONAL)
 
 		return generator.NewOpenAPIv3Generator(plugin, conf).Run()

diff --git a/cmd/protoc-gen-openapi/plugin_test.go b/cmd/protoc-gen-openapi/plugin_test.go
@@ -36,6 +36,7 @@ var openapiTests = []struct {
 	{name: "JSON options", path: "examples/tests/jsonoptions/", protofile: "message.proto"},
 	{name: "Ignore services without annotations", path: "examples/tests/noannotations/", protofile: "message.proto"},
 	{name: "Enum Options", path: "examples/tests/enumoptions/", protofile: "message.proto"},
+	{name: "OpenAPIv3 Annotations", path: "examples/tests/openapiv3annotations/", protofile: "message.proto"},
 }
 
 // Set this to true to generate/overwrite the fixtures. Make sure you set it back