diff --git a/examples/internal/clients/abe/api/swagger.yaml b/examples/internal/clients/abe/api/swagger.yaml index f77de5f7460..979d74dee97 100644 --- a/examples/internal/clients/abe/api/swagger.yaml +++ b/examples/internal/clients/abe/api/swagger.yaml @@ -4807,6 +4807,7 @@ definitions: type: "integer" format: "int64" ok: + description: "DeepEnum description." $ref: "#/definitions/NestedDeepEnum" description: "Nested is nested type." example: @@ -4939,6 +4940,8 @@ definitions: items: $ref: "#/definitions/examplepbNumericEnum" enumValueAnnotation: + description: "Numeric enum description." + title: "Numeric enum title" $ref: "#/definitions/examplepbNumericEnum" repeatedStringAnnotation: type: "array" @@ -4953,6 +4956,8 @@ definitions: items: $ref: "#/definitions/ABitOfEverythingNested" nestedAnnotation: + description: "Nested object description." + title: "Nested object title" $ref: "#/definitions/ABitOfEverythingNested" int64OverrideType: type: "integer" @@ -5444,6 +5449,8 @@ definitions: items: $ref: "#/definitions/examplepbNumericEnum" enumValueAnnotation: + description: "Numeric enum description." + title: "Numeric enum title" $ref: "#/definitions/examplepbNumericEnum" repeatedStringAnnotation: type: "array" @@ -5458,6 +5465,8 @@ definitions: items: $ref: "#/definitions/ABitOfEverythingNested" nestedAnnotation: + description: "Nested object description." + title: "Nested object title" $ref: "#/definitions/ABitOfEverythingNested" int64OverrideType: type: "integer" @@ -5523,6 +5532,7 @@ definitions: type: "integer" format: "int64" ok: + description: "DeepEnum description." $ref: "#/definitions/NestedDeepEnum" description: "Nested is nested type." example: "{\"ok\":\"TRUE\"}" @@ -5640,6 +5650,8 @@ definitions: items: $ref: "#/definitions/examplepbNumericEnum" enumValueAnnotation: + description: "Numeric enum description." + title: "Numeric enum title" $ref: "#/definitions/examplepbNumericEnum" repeatedStringAnnotation: type: "array" @@ -5654,6 +5666,8 @@ definitions: items: $ref: "#/definitions/ABitOfEverythingNested" nestedAnnotation: + description: "Nested object description." + title: "Nested object title" $ref: "#/definitions/ABitOfEverythingNested" int64OverrideType: type: "integer" @@ -5836,6 +5850,8 @@ definitions: items: $ref: "#/definitions/examplepbNumericEnum" enumValueAnnotation: + description: "Numeric enum description." + title: "Numeric enum title" $ref: "#/definitions/examplepbNumericEnum" repeatedStringAnnotation: type: "array" @@ -5850,6 +5866,8 @@ definitions: items: $ref: "#/definitions/ABitOfEverythingNested" nestedAnnotation: + description: "Nested object description." + title: "Nested object title" $ref: "#/definitions/ABitOfEverythingNested" int64OverrideType: type: "integer" @@ -6017,6 +6035,8 @@ definitions: items: $ref: "#/definitions/examplepbNumericEnum" enumValueAnnotation: + description: "Numeric enum description." + title: "Numeric enum title" $ref: "#/definitions/examplepbNumericEnum" repeatedStringAnnotation: type: "array" @@ -6031,6 +6051,8 @@ definitions: items: $ref: "#/definitions/ABitOfEverythingNested" nestedAnnotation: + description: "Nested object description." + title: "Nested object title" $ref: "#/definitions/ABitOfEverythingNested" int64OverrideType: type: "integer" @@ -6188,6 +6210,8 @@ definitions: items: $ref: "#/definitions/examplepbNumericEnum" enumValueAnnotation: + description: "Numeric enum description." + title: "Numeric enum title" $ref: "#/definitions/examplepbNumericEnum" repeatedStringAnnotation: type: "array" @@ -6202,6 +6226,8 @@ definitions: items: $ref: "#/definitions/ABitOfEverythingNested" nestedAnnotation: + description: "Nested object description." + title: "Nested object title" $ref: "#/definitions/ABitOfEverythingNested" int64OverrideType: type: "integer" diff --git a/examples/internal/clients/abe/model_a_bit_of_everything.go b/examples/internal/clients/abe/model_a_bit_of_everything.go index 54ee6d4d7a8..25a28dc37d9 100644 --- a/examples/internal/clients/abe/model_a_bit_of_everything.go +++ b/examples/internal/clients/abe/model_a_bit_of_everything.go @@ -48,11 +48,13 @@ type ABitOfEverything struct { RepeatedEnumValue []ExamplepbNumericEnum `json:"repeatedEnumValue,omitempty"` // Repeated numeric enum description. RepeatedEnumAnnotation []ExamplepbNumericEnum `json:"repeatedEnumAnnotation,omitempty"` + // Numeric enum description. EnumValueAnnotation *ExamplepbNumericEnum `json:"enumValueAnnotation,omitempty"` // Repeated string description. RepeatedStringAnnotation []string `json:"repeatedStringAnnotation,omitempty"` // Repeated nested object description. RepeatedNestedAnnotation []ABitOfEverythingNested `json:"repeatedNestedAnnotation,omitempty"` + // Nested object description. NestedAnnotation *ABitOfEverythingNested `json:"nestedAnnotation,omitempty"` Int64OverrideType int64 `json:"int64OverrideType,omitempty"` RequiredStringViaFieldBehaviorAnnotation string `json:"requiredStringViaFieldBehaviorAnnotation"` diff --git a/examples/internal/clients/abe/model_a_bit_of_everything_1.go b/examples/internal/clients/abe/model_a_bit_of_everything_1.go index 1dc59cdd84e..75a9ea1ee48 100644 --- a/examples/internal/clients/abe/model_a_bit_of_everything_1.go +++ b/examples/internal/clients/abe/model_a_bit_of_everything_1.go @@ -49,11 +49,13 @@ type ABitOfEverything1 struct { RepeatedEnumValue []ExamplepbNumericEnum `json:"repeatedEnumValue,omitempty"` // Repeated numeric enum description. RepeatedEnumAnnotation []ExamplepbNumericEnum `json:"repeatedEnumAnnotation,omitempty"` + // Numeric enum description. EnumValueAnnotation *ExamplepbNumericEnum `json:"enumValueAnnotation,omitempty"` // Repeated string description. RepeatedStringAnnotation []string `json:"repeatedStringAnnotation,omitempty"` // Repeated nested object description. RepeatedNestedAnnotation []ABitOfEverythingNested `json:"repeatedNestedAnnotation,omitempty"` + // Nested object description. NestedAnnotation *ABitOfEverythingNested `json:"nestedAnnotation,omitempty"` Int64OverrideType int64 `json:"int64OverrideType,omitempty"` RequiredStringViaFieldBehaviorAnnotation string `json:"requiredStringViaFieldBehaviorAnnotation"` diff --git a/examples/internal/clients/abe/model_a_bit_of_everything_2.go b/examples/internal/clients/abe/model_a_bit_of_everything_2.go index dc648a75c67..28c009de5ca 100644 --- a/examples/internal/clients/abe/model_a_bit_of_everything_2.go +++ b/examples/internal/clients/abe/model_a_bit_of_everything_2.go @@ -48,11 +48,13 @@ type ABitOfEverything2 struct { RepeatedEnumValue []ExamplepbNumericEnum `json:"repeatedEnumValue,omitempty"` // Repeated numeric enum description. RepeatedEnumAnnotation []ExamplepbNumericEnum `json:"repeatedEnumAnnotation,omitempty"` + // Numeric enum description. EnumValueAnnotation *ExamplepbNumericEnum `json:"enumValueAnnotation,omitempty"` // Repeated string description. RepeatedStringAnnotation []string `json:"repeatedStringAnnotation,omitempty"` // Repeated nested object description. RepeatedNestedAnnotation []ABitOfEverythingNested `json:"repeatedNestedAnnotation,omitempty"` + // Nested object description. NestedAnnotation *ABitOfEverythingNested `json:"nestedAnnotation,omitempty"` Int64OverrideType int64 `json:"int64OverrideType,omitempty"` RequiredStringViaFieldBehaviorAnnotation string `json:"requiredStringViaFieldBehaviorAnnotation"` diff --git a/examples/internal/clients/abe/model_a_bit_of_everything_3.go b/examples/internal/clients/abe/model_a_bit_of_everything_3.go index 448a1b0303d..464e7f875c2 100644 --- a/examples/internal/clients/abe/model_a_bit_of_everything_3.go +++ b/examples/internal/clients/abe/model_a_bit_of_everything_3.go @@ -48,11 +48,13 @@ type ABitOfEverything3 struct { RepeatedEnumValue []ExamplepbNumericEnum `json:"repeatedEnumValue,omitempty"` // Repeated numeric enum description. RepeatedEnumAnnotation []ExamplepbNumericEnum `json:"repeatedEnumAnnotation,omitempty"` + // Numeric enum description. EnumValueAnnotation *ExamplepbNumericEnum `json:"enumValueAnnotation,omitempty"` // Repeated string description. RepeatedStringAnnotation []string `json:"repeatedStringAnnotation,omitempty"` // Repeated nested object description. RepeatedNestedAnnotation []ABitOfEverythingNested `json:"repeatedNestedAnnotation,omitempty"` + // Nested object description. NestedAnnotation *ABitOfEverythingNested `json:"nestedAnnotation,omitempty"` Int64OverrideType int64 `json:"int64OverrideType,omitempty"` RequiredStringViaFieldBehaviorAnnotation string `json:"requiredStringViaFieldBehaviorAnnotation"` diff --git a/examples/internal/clients/abe/model_a_bit_of_everything_4.go b/examples/internal/clients/abe/model_a_bit_of_everything_4.go index f877d26f253..c26d449ef07 100644 --- a/examples/internal/clients/abe/model_a_bit_of_everything_4.go +++ b/examples/internal/clients/abe/model_a_bit_of_everything_4.go @@ -48,11 +48,13 @@ type ABitOfEverything4 struct { RepeatedEnumValue []ExamplepbNumericEnum `json:"repeatedEnumValue,omitempty"` // Repeated numeric enum description. RepeatedEnumAnnotation []ExamplepbNumericEnum `json:"repeatedEnumAnnotation,omitempty"` + // Numeric enum description. EnumValueAnnotation *ExamplepbNumericEnum `json:"enumValueAnnotation,omitempty"` // Repeated string description. RepeatedStringAnnotation []string `json:"repeatedStringAnnotation,omitempty"` // Repeated nested object description. RepeatedNestedAnnotation []ABitOfEverythingNested `json:"repeatedNestedAnnotation,omitempty"` + // Nested object description. NestedAnnotation *ABitOfEverythingNested `json:"nestedAnnotation,omitempty"` Int64OverrideType int64 `json:"int64OverrideType,omitempty"` RequiredStringViaFieldBehaviorAnnotation string `json:"requiredStringViaFieldBehaviorAnnotation,omitempty"` diff --git a/examples/internal/clients/abe/model_a_bit_of_everything_nested.go b/examples/internal/clients/abe/model_a_bit_of_everything_nested.go index a90f8e75207..586778feaaa 100644 --- a/examples/internal/clients/abe/model_a_bit_of_everything_nested.go +++ b/examples/internal/clients/abe/model_a_bit_of_everything_nested.go @@ -15,5 +15,6 @@ type ABitOfEverythingNested struct { // name is nested field. Name string `json:"name,omitempty"` Amount int64 `json:"amount,omitempty"` + // DeepEnum description. Ok *NestedDeepEnum `json:"ok,omitempty"` } diff --git a/examples/internal/clients/abe/model_examplepb_a_bit_of_everything.go b/examples/internal/clients/abe/model_examplepb_a_bit_of_everything.go index add20a6133e..04a06e37dfb 100644 --- a/examples/internal/clients/abe/model_examplepb_a_bit_of_everything.go +++ b/examples/internal/clients/abe/model_examplepb_a_bit_of_everything.go @@ -49,11 +49,13 @@ type ExamplepbABitOfEverything struct { RepeatedEnumValue []ExamplepbNumericEnum `json:"repeatedEnumValue,omitempty"` // Repeated numeric enum description. RepeatedEnumAnnotation []ExamplepbNumericEnum `json:"repeatedEnumAnnotation,omitempty"` + // Numeric enum description. EnumValueAnnotation *ExamplepbNumericEnum `json:"enumValueAnnotation,omitempty"` // Repeated string description. RepeatedStringAnnotation []string `json:"repeatedStringAnnotation,omitempty"` // Repeated nested object description. RepeatedNestedAnnotation []ABitOfEverythingNested `json:"repeatedNestedAnnotation,omitempty"` + // Nested object description. NestedAnnotation *ABitOfEverythingNested `json:"nestedAnnotation,omitempty"` Int64OverrideType int64 `json:"int64OverrideType,omitempty"` RequiredStringViaFieldBehaviorAnnotation string `json:"requiredStringViaFieldBehaviorAnnotation"` diff --git a/examples/internal/clients/abe/model_v1exampledeep_pathsingle_nested_name_single_nested.go b/examples/internal/clients/abe/model_v1exampledeep_pathsingle_nested_name_single_nested.go index 1997ba73ca9..3ab04604db7 100644 --- a/examples/internal/clients/abe/model_v1exampledeep_pathsingle_nested_name_single_nested.go +++ b/examples/internal/clients/abe/model_v1exampledeep_pathsingle_nested_name_single_nested.go @@ -13,5 +13,6 @@ package abe // Nested is nested type. type V1exampledeepPathsingleNestedNameSingleNested struct { Amount int64 `json:"amount,omitempty"` + // DeepEnum description. Ok *NestedDeepEnum `json:"ok,omitempty"` } diff --git a/examples/internal/proto/examplepb/a_bit_of_everything.swagger.json b/examples/internal/proto/examplepb/a_bit_of_everything.swagger.json index eb4ac1e3278..914106787e4 100644 --- a/examples/internal/proto/examplepb/a_bit_of_everything.swagger.json +++ b/examples/internal/proto/examplepb/a_bit_of_everything.swagger.json @@ -2480,7 +2480,9 @@ "title": "Repeated numeric enum title" }, "enumValueAnnotation": { - "$ref": "#/definitions/examplepbNumericEnum" + "$ref": "#/definitions/examplepbNumericEnum", + "description": "Numeric enum description.", + "title": "Numeric enum title" }, "repeatedStringAnnotation": { "type": "array", @@ -2499,7 +2501,9 @@ "title": "Repeated nested object title" }, "nestedAnnotation": { - "$ref": "#/definitions/ABitOfEverythingNested" + "$ref": "#/definitions/ABitOfEverythingNested", + "description": "Nested object description.", + "title": "Nested object title" }, "int64OverrideType": { "type": "integer", @@ -4724,7 +4728,8 @@ "format": "int64" }, "ok": { - "$ref": "#/definitions/NestedDeepEnum" + "$ref": "#/definitions/NestedDeepEnum", + "description": "DeepEnum description." } }, "description": "Nested is nested type." @@ -4864,7 +4869,9 @@ "title": "Repeated numeric enum title" }, "enumValueAnnotation": { - "$ref": "#/definitions/examplepbNumericEnum" + "$ref": "#/definitions/examplepbNumericEnum", + "description": "Numeric enum description.", + "title": "Numeric enum title" }, "repeatedStringAnnotation": { "type": "array", @@ -4883,7 +4890,9 @@ "title": "Repeated nested object title" }, "nestedAnnotation": { - "$ref": "#/definitions/ABitOfEverythingNested" + "$ref": "#/definitions/ABitOfEverythingNested", + "description": "Nested object description.", + "title": "Nested object title" }, "int64OverrideType": { "type": "integer", @@ -5521,7 +5530,9 @@ "title": "Repeated numeric enum title" }, "enumValueAnnotation": { - "$ref": "#/definitions/examplepbNumericEnum" + "$ref": "#/definitions/examplepbNumericEnum", + "description": "Numeric enum description.", + "title": "Numeric enum title" }, "repeatedStringAnnotation": { "type": "array", @@ -5540,7 +5551,9 @@ "title": "Repeated nested object title" }, "nestedAnnotation": { - "$ref": "#/definitions/ABitOfEverythingNested" + "$ref": "#/definitions/ABitOfEverythingNested", + "description": "Nested object description.", + "title": "Nested object title" }, "int64OverrideType": { "type": "integer", @@ -5828,7 +5841,9 @@ "title": "Repeated numeric enum title" }, "enumValueAnnotation": { - "$ref": "#/definitions/examplepbNumericEnum" + "$ref": "#/definitions/examplepbNumericEnum", + "description": "Numeric enum description.", + "title": "Numeric enum title" }, "repeatedStringAnnotation": { "type": "array", @@ -5847,7 +5862,9 @@ "title": "Repeated nested object title" }, "nestedAnnotation": { - "$ref": "#/definitions/ABitOfEverythingNested" + "$ref": "#/definitions/ABitOfEverythingNested", + "description": "Nested object description.", + "title": "Nested object title" }, "int64OverrideType": { "type": "integer", @@ -6645,7 +6662,9 @@ "title": "Repeated numeric enum title" }, "enumValueAnnotation": { - "$ref": "#/definitions/examplepbNumericEnum" + "$ref": "#/definitions/examplepbNumericEnum", + "description": "Numeric enum description.", + "title": "Numeric enum title" }, "repeatedStringAnnotation": { "type": "array", @@ -6664,7 +6683,9 @@ "title": "Repeated nested object title" }, "nestedAnnotation": { - "$ref": "#/definitions/ABitOfEverythingNested" + "$ref": "#/definitions/ABitOfEverythingNested", + "description": "Nested object description.", + "title": "Nested object title" }, "int64OverrideType": { "type": "integer", @@ -6836,7 +6857,8 @@ "format": "int64" }, "ok": { - "$ref": "#/definitions/NestedDeepEnum" + "$ref": "#/definitions/NestedDeepEnum", + "description": "DeepEnum description." } }, "description": "Nested is nested type." @@ -7003,7 +7025,9 @@ "title": "Repeated numeric enum title" }, "enumValueAnnotation": { - "$ref": "#/definitions/examplepbNumericEnum" + "$ref": "#/definitions/examplepbNumericEnum", + "description": "Numeric enum description.", + "title": "Numeric enum title" }, "repeatedStringAnnotation": { "type": "array", @@ -7022,7 +7046,9 @@ "title": "Repeated nested object title" }, "nestedAnnotation": { - "$ref": "#/definitions/ABitOfEverythingNested" + "$ref": "#/definitions/ABitOfEverythingNested", + "description": "Nested object description.", + "title": "Nested object title" }, "int64OverrideType": { "type": "integer", diff --git a/examples/internal/proto/examplepb/generated_input.swagger.json b/examples/internal/proto/examplepb/generated_input.swagger.json index bcb7f081b55..9bd39c3155a 100644 --- a/examples/internal/proto/examplepb/generated_input.swagger.json +++ b/examples/internal/proto/examplepb/generated_input.swagger.json @@ -67,7 +67,8 @@ "format": "int64" }, "ok": { - "$ref": "#/definitions/NestedDeepEnum" + "$ref": "#/definitions/NestedDeepEnum", + "description": "DeepEnum description." } }, "description": "Nested is nested type." @@ -234,7 +235,9 @@ "title": "Repeated numeric enum title" }, "enumValueAnnotation": { - "$ref": "#/definitions/examplepbNumericEnum" + "$ref": "#/definitions/examplepbNumericEnum", + "description": "Numeric enum description.", + "title": "Numeric enum title" }, "repeatedStringAnnotation": { "type": "array", @@ -253,7 +256,9 @@ "title": "Repeated nested object title" }, "nestedAnnotation": { - "$ref": "#/definitions/ABitOfEverythingNested" + "$ref": "#/definitions/ABitOfEverythingNested", + "description": "Nested object description.", + "title": "Nested object title" }, "int64OverrideType": { "type": "integer", diff --git a/examples/internal/proto/examplepb/stream.swagger.json b/examples/internal/proto/examplepb/stream.swagger.json index bb11e5bda83..6ece692db62 100644 --- a/examples/internal/proto/examplepb/stream.swagger.json +++ b/examples/internal/proto/examplepb/stream.swagger.json @@ -171,7 +171,8 @@ "format": "int64" }, "ok": { - "$ref": "#/definitions/NestedDeepEnum" + "$ref": "#/definitions/NestedDeepEnum", + "description": "DeepEnum description." } }, "description": "Nested is nested type." @@ -360,7 +361,9 @@ "title": "Repeated numeric enum title" }, "enumValueAnnotation": { - "$ref": "#/definitions/examplepbNumericEnum" + "$ref": "#/definitions/examplepbNumericEnum", + "description": "Numeric enum description.", + "title": "Numeric enum title" }, "repeatedStringAnnotation": { "type": "array", @@ -379,7 +382,9 @@ "title": "Repeated nested object title" }, "nestedAnnotation": { - "$ref": "#/definitions/ABitOfEverythingNested" + "$ref": "#/definitions/ABitOfEverythingNested", + "description": "Nested object description.", + "title": "Nested object title" }, "int64OverrideType": { "type": "integer", diff --git a/protoc-gen-openapiv2/internal/genopenapi/template.go b/protoc-gen-openapiv2/internal/genopenapi/template.go index 6c465e670af..7bbd8d643a8 100644 --- a/protoc-gen-openapiv2/internal/genopenapi/template.go +++ b/protoc-gen-openapiv2/internal/genopenapi/template.go @@ -516,12 +516,6 @@ func renderMessageAsDefinition(msg *descriptor.Message, reg *descriptor.Registry fieldSchema.Required = nil } - if fieldSchema.Ref != "" { - // Per the JSON Reference syntax: Any members other than "$ref" in a JSON Reference object SHALL be ignored. - // https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03#section-3 - fieldSchema = openapiSchemaObject{schemaCore: schemaCore{Ref: fieldSchema.Ref}} - } - kv := keyVal{Value: fieldSchema} kv.Key = reg.FieldName(f) if schema.Properties == nil { @@ -1238,12 +1232,6 @@ func renderServices(services []*descriptor.Service, paths openapiPathsObject, re } else { desc = fieldProtoComments(reg, bodyField.Target.Message, bodyField.Target) } - if schema.Ref != "" { - // Per the JSON Reference syntax: Any members other than "$ref" in a JSON Reference object SHALL be ignored. - // https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03#section-3 - schema = openapiSchemaObject{schemaCore: schemaCore{Ref: schema.Ref}} - } - } if meth.GetClientStreaming() {