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

Support x-enumNames for BackedEnums #1724

Open
wants to merge 2 commits into
base: master
Choose a base branch
from

Conversation

BusterNeece
Copy link
Contributor

Currently, in the OpenAPI spec, there's no standardized way to persist the name of enums when the value of the enum is stored in the enum value. There are competing implementations for providing this data in the form of extensions, but one with widespread support is x-enumNames, used by NSwag, swagger-api-typescript, and SwaggerUI via a plugin.

This PR specifically expands the enum processing to automatically generate the x-enumNames values in cases where the enum name isn't used as the value. This ensures that we're able to use this data in other libraries.

I figured I'd offer it as a PR since it may be of utility to more than just me, but I realize that it's using an extension and I can also implement it via directly modifying the pipeline myself. Either way, perhaps it's helpful for folks!

@DerManoMann
Copy link
Collaborator

I like it. Only thing I think should be changed is to make this optional.

Also, this page suggests a variety of different x- keys, so maybe allowing to specify it (at the same time) would make it even more useful...
https://stackoverflow.com/questions/66465888/how-to-define-enum-mapping-in-openapi

    protected ?string $enumNames;

    public function __construct(?string $enumNames = null)
    {
        $this->enumNames = $enumNames;
    }

    public function getEnumNames(): ?string
    {
        return $this->enumNames;
    }

And then the check would be

                if (!$useName && $this->enumNames) {
                    // ...
                    $schemaX[$this->enumNames] = array_map(function ($case) {

@DerManoMann
Copy link
Collaborator

The suggestion for using const for 3.1.0 is also interesting as it would avoid having to use extensions at all. Maybe that could be added later on and enumNames (or whatever is configured) only applies to 3.0.0

@BusterNeece
Copy link
Contributor Author

I haven't had the time to get back to this as a proper PR, but just as a note, I did go ahead and implement this as a standalone processor just to ensure it worked well for our purposes (and it works perfectly): https://github.com/AzuraCast/AzuraCast/blob/6fed28d138ed9900f7abee41d142ef7ed0407687/backend/src/OpenApi/AddXEnumNames.php

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

Successfully merging this pull request may close these issues.

2 participants