Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[REQ] Support for OpenAPI 3.0-style documented enums #2834

Open
lemoinem opened this issue May 6, 2019 · 3 comments
Open

[REQ] Support for OpenAPI 3.0-style documented enums #2834

lemoinem opened this issue May 6, 2019 · 3 comments

Comments

@lemoinem
Copy link
Contributor

lemoinem commented May 6, 2019

Is your feature request related to a problem? Please describe.

With OpenAPI 3.0 there a pattern that allows to document integer-based enums without having to rely on x-enum-varnames and x-enum-descriptions: OAI/OpenAPI-Specification#681 (comment)

Describe the solution you'd like

It would be great to have this pattern supported. Currently, it doesn't generate anything.

Describe alternatives you've considered

We can keep using the old vendor extensions for now. But it would be great to support the new pattern as well.

Additional context

None that I can see.

@jmini
Copy link
Member

jmini commented May 9, 2019

This is a duplicate for #1693

Documentation for this feature can be found here: https://openapi-generator.tech/docs/templating#all-generators-core

Which version are you using and which generator? It works well for java with 4.0.0 (I am using the latest beta)

I did not read carefully the message.

openapi: 3.0.1
info:
  title: ping test
  version: '1.0'
servers:
  - url: 'http://localhost:9999/'
paths:
  /ping:
    get:
      operationId: pingGet
      responses:
        '201':
          description: OK
components:
  schemas:
    SomeObj:
      type: object
      properties:
        someProp:
          oneOf:
            - enum: [1]
              title: Sunny
              description: Blue sky
            - enum: [2]
              title: Cloudy
              description: Slightly overcast
            - enum: [3]
              title: Rainy
              description: Take an umbrella with you

We could support this, but I am not sure if this is better than x-enum-descriptions.
I am also not sure how much other OpenAPI tool support this (I just tried Swagger-UI and there it is also not the case.).

@lemoinem
Copy link
Contributor Author

lemoinem commented May 9, 2019

I understand the point. But if all the major tool implementors follow the same line of thoughts, it will never get supported.

Which is not necessarily an issue in itself. However, since it's the recommended way to describe enums by the folks designing JSON-schema and OpenAPI themselves. I believe it would still be great to at least keep it somewhere in the backlog.

Since it looks like something relatively easy to implement, maybe keep it tagged with "help wanted"?
If I can get some time to get around to it, I would be happy to implement it myself actually. Would you accept a PR for such support?

It wouldn't generate new data structure for the generators, just generate the same as what x-enum-names and x-enum-descriptions already do.

@grokify
Copy link
Member

grokify commented Oct 19, 2022

I am not sure if this is better than x-enum-descriptions.

It seems like this would solve the parallel arrays issue for using x-enum-descriptions and x-enum-names together.

Regarding the comparison with x-enum-descriptions, is this more comparable to x-enum-values described in this PR:

#1486

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants