Swashbuckle.aspnetcore: Question: How can we take enums as references?

[alexdrl]

Hello, we have an ASP.NET Core API from which we generate a swagger.json from this package (we love it).

One problem that we have is that we want to codegen the same enum not only as strings, but generate it using swagger.json refs. We modified the swagger.json manually and this is possible, we could generate code with NSwag and the enums are generalized.

I annotated the methods which return an enum without luck, how can we achieve that?

[mkontula]

We have pretty much the same issue. Some controller methods have enums as their route or query parameters. This leads to multiple definition of enums in generated client code. I'd rather have one enum defined in definitions and referenced as parameter which swagger definition supports. Manually editing the generated swagger.json is a huge antipatterns because humans are involved.

[william-lohan]

It seems you can't have definitions for query parameters SO: Swagger: Reusing an enum definition as query parameter > links to but (nevermind) I have the same issue for body parameters. I made a sample.

If you go to swagger/v1/swagger.json you get

    "definitions": {
        "ModelA": {
            "type": "object",
            "properties": {
                "option": {
                    "format": "int32",
                    "enum": [
                        0,
                        1,
                        2
                    ],
                    "type": "integer"
                }
            }
        },
        "ModelB": {
            "type": "object",
            "properties": {
                "option": {
                    "format": "int32",
                    "enum": [
                        0,
                        1,
                        2
                    ],
                    "type": "integer"
                }
            }
        }
    },

The desired result would be

    "definitions": {
        "ModelA": {
            "type": "object",
            "properties": {
                "option": {
                    "$ref": "#/definitions/MyEnum"
                }
            }
        },
        "ModelB": {
            "type": "object",
            "properties": {
                "option": {
                    "$ref": "#/definitions/MyEnum"
                }
            }
        },
        "MyEnum": {
            "format": "int32",
            "enum": [
                0,
                1,
                2
            ],
            "type": "integer"
        }
    },

I tired c.MapType<MyEnum>(() => new Schema { Ref = "#/definitions/MyEnum" }); but only got

    "definitions": {
        "ModelA": {
            "type": "object",
            "properties": {
                "option": {
                    "$ref": "#/definitions/MyEnum"
                }
            }
        },
        "ModelB": {
            "type": "object",
            "properties": {
                "option": {
                    "$ref": "#/definitions/MyEnum"
                }
            }
        }
    },

[onionhammer]

This is definitely a barrier for incorporating swagger gen over our existing solution..

[domaindrivendev]

This should be a relatively straightforward change. Anyone on this thread interest in submitting a PR? This is FOSS afterall :)

[onionhammer]

@domaindrivendev true, but it would take someone fresh to this project much more time and effort than someone very familiar with this project hint hint ;)

I am willing to try, I see something in here called a 'SchemaRegistry', which sounds promising, but i have no idea how this solution is structured

[onionhammer]

Well, the code is there, hopefully @domaindrivendev takes a look. I only generate the enum for 'string' enums, since integer enums in swagger dont contain enough data to really generate friendly enum names in the targeted language anyway.

[onionhammer]

Bumpty bump

[onionhammer]

Does anyone who maintains this project want to weigh in? There are multiple issues surrounding this same question of basic enum support....

[domaindrivendev]

This is issue is partially solved by the above PR. See the PR comments

Using referenced definitions for enum parameters in path, query or headers still isn't possible due to limitations with the Swagger 2.0 specification. So, we'll need to build in OpenApi v3 support to fully resolve. This is coming but is a heavier lift.

[bugproof]

Query or headers still isn't possible due to limitations with the Swagger 2.0 specification. So, we'll need to build in OpenApi v3 support to fully resolve. This is coming but is a heavier lift.

I was looking for this feature today but I realized it's v3 which swashbuckle doesn't support.

[domaindrivendev]

As of https://github.com/domaindrivendev/Swashbuckle.AspNetCore/pull/1041, enums are generated as references by default