openapiv2_field for enum field don't show in swagger page

[magichan]

🐛 Bug Report

enum openapiv2_field setting should show a description in swagger UI page, the swagger.json have the content but don't show in swagger UI page

To Reproduce

1. git clone git@github.com:magichan/openapibug.git
2. buf generate
3. chmod 777 docs/proto/pet/v1/pet.swagger.json
4. docker run --rm -p 12322:8080 -e SWAGGER_JSON=/pet.swagger.json -v ${PWD}/docs/proto/pet/v1/pet.swagger.json:/pet.swagger.json swaggerapi/swagger-ui

in openapibug repo, we have openapiv2_field setting for pet_category_2 ,

  PetCategory pet_category_2 = 5 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
    title: "options comment as title[it don't work]"
  }];

the generation swagger json file has the title,

but the swagger UI doesn't show the title for pet_category_2

Expected behavior

the swagger UI show the title for pet_category_2

Actual Behavior

the swagger UI doesn't show the title for pet_category_2

Your Environment

buf version 1.15.0
Ubuntu 18.04.6 LTS

[johanbrandhorst]

Hi, thanks for your issue! This seems to be a question for the developers of the Swagger UI project: https://github.com/swagger-api/swagger-ui. Maybe you can raise an issue with them? I would recommend simply sharing your swagger file and the expected behavior, all the Protobuf generation stuff is probably only going to confuse the issue report. Hope that helps!

[magichan]

@johanbrandhorst add swagger.json to https://editor.swagger.io/

the editor reports a warning

sibling properties ignored when using $ref.

[magichan]

based on https://stackoverflow.com/questions/33629750/swagger-schema-properties-ignored-when-using-ref-why,

We believe the data generated by the Open API in v3.1 format, but the JSON declares itself as v2.

We apply to reopen this issue @johanbrandhorst

[johanbrandhorst]

I'm not sure what you're expecting here. Your title annotation is on a field with a type of v1PetCategory, not on the enum itself. Where else do you want that comment to go? It can't go in the ref'd type. See more discussion on this behavior here: #3058 (comment).

[magichan]

After I read #3058 (comment) , I concluded that,

The title attribute of the current enumeration field is placed in the sibling position of $ref, which is a compromise that currently works for some tools but does not work for some tools(swagger UI or openapi-generator).

Is this summary correct?

[johanbrandhorst]

Yes, it seems that way. I think we could perhaps consider this problem an extension of #3058?

[magichan]

ok, we will track our problem with #3058.