openapiv2: Field options are not properly rendered for repeated fields

[sumabn]

I need to generate swagger json using proto annotations.
generated schema should look like this

"schema": {
              "type": "object",
              "example": {
                "product_id": ["8900099100000113079", "8900099100000082373"]
              },
              "properties": {
                "product_id": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "maxLength": 19,
                   "minLength": 1,
                   "pattern": "^[0-9]+$"
                  },
                  "description": "Only digits are allowed.",
                  "title": "Provide list of ids"           
                }
              }
            }

and the annotation added was something like this

message product { 
repeated string product_id=1[(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
                  pattern: "^[0-9]+$"
                  max_length: 19
                  min_length: 1
                  description: "Only digits are allowed."
    }];
}

But the problem is above annotation is generating schema like this

"schema": {
              "type": "object",
              "example": {
                "product_id": ["8900099100000113079", "8900099100000082373"]
              },
              "properties": {
                "product_id": {
                  "type": "array",
                  "items": {
                    "type": "string"                   
                  },
                  "description": "Only digits are allowed.",
                  "title": "Provide list of ids",
                   "maxLength": 19,
                   "minLength": 1,
                   "pattern": "^[0-9]+$"           
                }
              }
            }

which is not correct. We could not find the relevant example in a_bit_of_everything.proto.

Please help in adding the annotations.

[johanbrandhorst]

Hi! I went and looked at the OpenAPIv2 spec and it seems you can specify the field properties both at the top level and inside the items object: https://swagger.io/specification/v2/#items-object. I think we should probably put it inside the items if the specified field is repeated. Would you be willing to help contribute a fix for this?

The easiest way to get started would be to add a new test to https://github.com/grpc-ecosystem/grpc-gateway/blob/master/protoc-gen-openapiv2/internal/genopenapi/template_test.go that would have the expected behavior. Having had a quick glance at the code, I think you'll need to make the changes here:

grpc-gateway/protoc-gen-openapiv2/internal/genopenapi/template.go

Line 398 in bfda18d

func renderMessageAsDefinition(msg *descriptor.Message, reg *descriptor.Registry, customRefs refMap, excludeFields []*descriptor.Field) openapiSchemaObject {

, but I could be wrong.

[lakshkeswani]

/assign @johanbrandhorst i am willing to contribute on this kindly assign it to me

[johanbrandhorst]

Hi @lakshkeswani, please have at it!

[jan-sykora]

We're dealing with similar issue. Our proto file:

import "google/protobuf/field_mask.proto";

message SomeMessage {
  google.protobuf.FieldMask update_mask = 10;
}

(Here's the definition of FieldMask:)

// google/protobuf/field_mask.proto

message FieldMask {
  // The set of field mask paths.
  repeated string paths = 1;
}

is generated into openapiv2 spec as:

"parameters": [
  {
    "name": "updateMask",
    "in": "query",
    "type": "string"
  }
]

The issue is that FieldMask should be generated into OpenAPI as a "type": "array" (expected) but it is generated as a "type": "string" (actual).

[johanbrandhorst]

This sounds like a separate issue, could you create a separate issue and share your RPC definition too please?

[jan-sykora]

@johanbrandhorst I have created a separate issue #2580 with reproducible example.

[wjkoh]

This change prevents setting min_length and max_length for the repeated field itself, I believe. Can we limit the number of product IDs to 4 in OpenAPI for repeated string product_id = 1; like this?

{
    "type": "array",
    "items": {
        "type": "string"
        // not here
    }
    // here
    "maxLength": 4
}

[johanbrandhorst]

I'm not sure what you're asking exactly? I'm not an expert on the OpenAPI spec. Do you have an example protobuf file you're using?

[wjkoh]

Let's use the same proto definition as an example:

message Order { 
  repeated string product_ids = 1 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
    max_length: 10
  }];
}

Suppose we have an order containing multiple product IDs. We want to limit the maximum number of product IDs to 10. I initially thought the above annotation would achieve this, but based on the changes mentioned in the issue, it appears that this annotation actually limits the length of each product ID string (e.g., "PROD123") to 10 characters, not the total number of product IDs to 10. Is this interpretation correct?

If so, could you please advise on how to limit the number of items in a repeated field in the OpenAPI v2 specification?

[johanbrandhorst]

I believe your interpretation is right. To my knowledge there is no way to do what you want with OpenAPI. Perhaps you want something like https://github.com/bufbuild/protoc-gen-validate?

[wjkoh]

I believe your interpretation is right. To my knowledge there is no way to do what you want with OpenAPI. Perhaps you want something like https://github.com/bufbuild/protoc-gen-validate?

OpenAPI supports it. It's called "minItems" and "maxItems". See https://stackoverflow.com/questions/57035988/how-to-limit-my-swagger-definition-array-to-be-either-0-or-3 for example. However, there's no way that we can generate minItems and maxItems for repeated fields using protoc_gen_openapiv2 afaik.