protoc-gen-openapiv2: Add field and schema extensions (grpc-ecosystem…

…#2418) * Field and schema extensions * Remove extensions from Schema As they are already included in JSONSchema * Add documentation for extensions
ysq5202121 · Apr 14, 2022 · 06128de · 06128de
1 parent 31a16c5
commit 06128de
Show file tree

Hide file tree

Showing 12 changed files with 1,109 additions and 977 deletions.
diff --git a/docs/docs/mapping/customizing_openapi_output.md b/docs/docs/mapping/customizing_openapi_output.md
@@ -39,6 +39,12 @@ message ABitOfEverything {
             description: "Find out more about ABitOfEverything";
         }
         example: "{\"uuid\": \"0cf361e1-4b44-483d-a159-54dabdf7e814\"}"
+        extensions: {
+            key: "x-irreversible";
+            value {
+                bool_value: true;
+            }
+        }
     };
 
     string uuid = 1 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {description: "The UUID field."}];
@@ -78,6 +84,29 @@ service ABitOfEverythingService {
 }
 ```
 
+[Swagger Extensions](https://swagger.io/docs/specification/2-0/swagger-extensions/) can be added as key-value pairs to the options. Keys must begin with `x-` and values can be of any type listed [here](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#value). For example:
+```
+extensions: {
+  key: "x-amazon-apigateway-authorizer";
+  value {
+    struct_value {
+      fields {
+        key: "type";
+        value {
+          string_value: "token";
+        }
+      }
+      fields {
+        key: "authorizerResultTtlInSeconds";
+        value {
+          number_value: 60;
+        }
+      }
+    }
+  }
+}
+```
+
 Please see this [a_bit_of_everything.proto](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/examples/internal/proto/examplepb/a_bit_of_everything.proto) for examples of the options being used.
 
 ## Using google.api.field_behavior

diff --git a/examples/internal/clients/abe/api/swagger.yaml b/examples/internal/clients/abe/api/swagger.yaml
@@ -159,6 +159,7 @@ paths:
         required: false
         type: "string"
         pattern: "[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}"
+        x-internal: true
         x-exportParamName: "Uuid"
         x-optionalDataType: "String"
       - name: "floatValue"
@@ -472,6 +473,7 @@ paths:
         required: false
         type: "string"
         pattern: "[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}"
+        x-internal: true
         x-exportParamName: "Uuid"
         x-optionalDataType: "String"
       - name: "floatValue"
@@ -776,6 +778,7 @@ paths:
         required: false
         type: "string"
         pattern: "[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}"
+        x-internal: true
         x-exportParamName: "Uuid"
         x-optionalDataType: "String"
       - name: "floatValue"
@@ -1069,6 +1072,7 @@ paths:
         in: "path"
         required: true
         type: "string"
+        x-internal: true
         x-exportParamName: "UuidName"
       - name: "singleNested.name"
         in: "query"
@@ -1549,6 +1553,7 @@ paths:
         required: false
         type: "string"
         pattern: "[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}"
+        x-internal: true
         x-exportParamName: "Uuid"
         x-optionalDataType: "String"
       - name: "bytesValue"
@@ -1702,6 +1707,7 @@ paths:
         in: "path"
         required: true
         type: "string"
+        x-internal: true
         x-exportParamName: "UuidName"
       - in: "body"
         name: "body"
@@ -2211,6 +2217,7 @@ paths:
         in: "path"
         required: true
         type: "string"
+        x-internal: true
         x-exportParamName: "UuidName"
       - in: "body"
         name: "abe"
@@ -2261,6 +2268,7 @@ paths:
         in: "path"
         required: true
         type: "string"
+        x-internal: true
         x-exportParamName: "UuidName"
       - in: "body"
         name: "abe"
@@ -2661,6 +2669,7 @@ paths:
         in: "path"
         required: true
         type: "string"
+        x-internal: true
         x-exportParamName: "UuidName"
       - in: "body"
         name: "body"
@@ -2798,6 +2807,7 @@ definitions:
         type: "string"
         minLength: 1
         pattern: "[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}"
+        x-internal: true
       nested:
         type: "array"
         items:
@@ -2932,6 +2942,7 @@ definitions:
     example:
       int64_value: 12
       double_value: 12.3
+    x-a-bit-of-everything-foo: "bar"
   examplepbABitOfEverythingRepeated:
     type: "object"
     properties:
@@ -3337,6 +3348,7 @@ definitions:
     example:
       int64_value: 12
       double_value: 12.3
+    x-a-bit-of-everything-foo: "bar"
   v1exampledeep_pathsingleNested.name_singleNested:
     properties:
       amount:
@@ -3362,6 +3374,7 @@ definitions:
         type: "string"
         minLength: 1
         pattern: "[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}"
+        x-internal: true
       nested:
         type: "array"
         items:
@@ -3496,6 +3509,7 @@ definitions:
     example:
       int64_value: 12
       double_value: 12.3
+    x-a-bit-of-everything-foo: "bar"
   The book to update.:
     type: "object"
     properties:
@@ -3655,6 +3669,7 @@ definitions:
     example:
       int64_value: 12
       double_value: 12.3
+    x-a-bit-of-everything-foo: "bar"
   A bit of everything_3:
     type: "object"
     required:
@@ -3799,6 +3814,7 @@ definitions:
     example:
       int64_value: 12
       double_value: 12.3
+    x-a-bit-of-everything-foo: "bar"
   A bit of everything_4:
     required:
     - "doubleValue"