Recursive Child elements do not generate correctly for OpenAPI

[hkf57]

🐛 Bug Report

Recursive child members do not render properly in OpenAPI

To Reproduce

For a given proto, generate the openapiv2 output (I used buf):

message Foo{
  repeated Foo children = 1;
}

Expected behavior

"Foo": {
"type": "object",
"properties": {
  "children": {
    "type": "array"
    "items": {
      "type": "object",
      "$ref": "#/Foo"
     }
    }
}

Actual Behavior

"Foo": {
"type": "object",
"properties": {
  "children": {
    "type": "array"
    "items": {
      "$ref": "#/Foo"
     }
    }
}

However, on the other hand, if your repeated section is NOT a recursive one, e.g. for the below proto:

message Bar {
  repeated Foo children = 1;
}

the generated openAPI spec looks like:

"Bar": {
"type": "object",
"properties": {
  "children": {
    "type": "array"
    "items": {
      "$ref": "#/Foo"
     }
    }
}

Which is totally valid.

I've tried both cases and it seems like even adding a type to the second example will work, so it looks like it can be added across the board for children.

Your Environment

Alpine 3.15, but reproducible everywhere

[johanbrandhorst]

Hi, thanks for your issue. I'm confused, aren't the two examples you show here identical? Why do you expect there to be a type field in the items object? There are plenty of examples in https://swagger.io/specification/v2 of items with just a ref field. Could you please clarify why this is wrong for the recursive type?

[hkf57]

Hi @johanbrandhorst, I think you're talking about the Actual Behaviour section, and the difference is only the top line.

Please see here for the requirement inside an array: https://swagger.io/specification/v2/#itemsObject

maybe, it is required for non-recursive references too. But the validator I'm using (the one inside https://github.com/opticdev/optic) seems to think it's fine.

[johanbrandhorst]

I did look at that definition, and it does state that type is required in the items object, but as you can see in multiple examples and evidently your validator too, it's not de facto required when using references. Are you experiencing an error associated with this behavior? Why should the non-recursive reference be OK and the recursive reference not be? I don't get it.

[hkf57]

@johanbrandhorst then it would be an inconsistency in the validator

Nonetheless it is still valid that the type is required if the items object has the type of array.

[johanbrandhorst]

I agree with that interpretation of the spec, I'm just surprised that their examples are... invalid code? In any case, it probably shouldn't hurt for us to add this. Would you be interested in contributing a fix?