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

Improve support for OpenAPI enum items that contain documentation #2481

Open
BDQ opened this issue Nov 29, 2024 · 0 comments
Open

Improve support for OpenAPI enum items that contain documentation #2481

BDQ opened this issue Nov 29, 2024 · 0 comments
Labels
feature-request A feature should be added or improved. OpenAPI

Comments

@BDQ
Copy link

BDQ commented Nov 29, 2024

Today, if I use the following Smithy enum definition:

@documentation("The status of the enrollment request.")
enum EnrollmentStatus {
  @documentation("The enrollment request is pending review.")
  PENDING = "PENDING",
  @documentation("The enrollment request has been approved.")
  APPROVED = "APPROVED",
  @documentation("The enrollment request has been rejected.")
  REJECTED = "REJECTED"
}

The following OpenAPI output will be produced, as can be seen below, the per item documentation lines are lost:

{
    "EnrollmentStatus": {
        "type": "string",
        "description": "The status of the enrollment. Only Stedi can set or update this property.",
        "enum": [
            "PENDING",
            "APPROVED",
            "REJECTED"
        ]
    }
}

Using OAS 3.1.x (and JSON Schema 2020-12) enums can be defined with oneOf along with const to allow documentation to included for each item, for example:

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"type": "object",
	"properties": {
		"status": {
			"type": "string",
			"description": "The status of the enrollment request.",
			"oneOf": [
				{
					"const": "PENDING",
					"description": "The enrollment request is pending."
				},
				{
					"const": "APPROVED",
					"description": "The enrollment request has been approved."
				},
				{
					"const": "REJECTED",
					"description": "The enrollment request has been rejected."
				}
			]
		}
	}
}

It would be great if we could have the same support in the openapi plugin.

@hpmellema hpmellema added feature-request A feature should be added or improved. OpenAPI labels Nov 29, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
feature-request A feature should be added or improved. OpenAPI
Projects
None yet
Development

No branches or pull requests

2 participants