Incorrect swagger.json generation when using FromForm parameters without the WithOpenApi extension method

[marcominerva]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

I have the following endpoints:

app.MapPost("/api/products", ([FromForm] Product product) =>
{
    return TypedResults.NoContent();
});

app.MapPost("/api/products-with-openapi", ([FromForm] Product product) =>
{
    return TypedResults.NoContent();
})
.WithOpenApi();

public record class Product(string Name, double Price);

These endpoints differ only for the WithOpenApi extension method, but the swagger.json definition is quite different:

"/api/products": {
  "post": {
    "tags": [
      "FromFormIssue"
    ],
    "requestBody": {
      "content": {
        "multipart/form-data": {
          "schema": {
            "required": [
              "product"
            ],
            "type": "object",
            "properties": {
              "product": {
                "$ref": "#/components/schemas/Product"
              }
            }
          },
          "encoding": {
            "product": {
              "style": "form"
            }
          }
        },
        "application/x-www-form-urlencoded": {
          "schema": {
            "required": [
              "product"
            ],
            "type": "object",
            "properties": {
              "product": {
                "$ref": "#/components/schemas/Product"
              }
            }
          },
          "encoding": {
            "product": {
              "style": "form"
            }
          }
        }
      }
    },
    "responses": {
      "204": {
        "description": "No Content"
      }
    }
  }
}


"/api/products-with-openapi": {
  "post": {
    "tags": [
      "FromFormIssue"
    ],
    "requestBody": {
      "content": {
        "multipart/form-data": {
          "schema": {
            "$ref": "#/components/schemas/Product"
          }
        },
        "application/x-www-form-urlencoded": {
          "schema": {
            "$ref": "#/components/schemas/Product"
          }
        }
      },
      "required": true
    },
    "responses": {
      "204": {
        "description": "No Content"
      }
    }
  }
}

So, in Swagger I get the following result:

WRONG

CORRECT

Expected Behavior

Both the endpoints should produce the same swagger.json definition that defines the parameters from Form.

Steps To Reproduce

Minimal repro here: https://github.com/marcominerva/FromFormIssue

Exceptions (if any)

No response

.NET Version

8.0.100

Anything else?

No response

[KennethHoff]

I just stumbled upon this problem as well. Good thing you made this issue or I probably wouldn't have found a (bandaid) fix like you did - as it involves a package I didn't realize existed.

[captainsafia]

The schema generation for each of these components is controlled by Swashbuckle.AspNetCore at the moment. To resolve this issue, we'd have to debug further into how the schema is mapped into the built-in OpenApiOperation in Swashbuckle to understand how the override is happening.

[KennethHoff]

Is there any discussion into creating a first party definition generator for AspNetCore? It doesn't need a full blown swagger UI and all that jazz, but just the json file would be lovely!

Swashbuckle hasn't had an update in almost a year, and NSwag currently doesn't support forms in Minimal APIs at all.

It feels weird how there's so much effort spent making the OpenAPI package and the API explorer and whatnot but seemingly in order to use it for anything useful you need a third party package (or write a lot of code yourself).

... Unless I've missed something and there is a built-in schema generator that I've managed to dodge through my web searches.

[captainsafia]

Is there any discussion into creating a first party definition generator for AspNetCore? It doesn't need a full blown swagger UI and all that jazz, but just the json file would be lovely!

Hopefully more on this front soon. 😅 I've done some prototyping on this in a sample branch but it needs considerable work before it can formalized.

Feedback that supporting just the OpenAPI document generation into a JSON file is great to share! I've always been of the opinion that an artifact that you can integrate with other systems (client generation, Postman, API management, etc.) is the most important aspect of this work.

[captainsafia]

I've verified that our built-in document generation is doing the right thing here and added some test coverage in #55321.

In the future, I plan on replating WithOpenApi on top of operation transformers so that there is a consistent experience here.

Closing this as resolved with a fix incoming in preview4.

[captainsafia]

In the future, I plan on replating WithOpenApi on top of operation transformers so that there is a consistent experience here.

Update: we ended up not pursuing this plan for WithOpenApi. See domaindrivendev/Swashbuckle.AspNetCore#2849.

In any case, the underlying issue is resolved in the built-in implementation. If there are still issues with Swashbuckle.AspNetCore, we should trakc them over there.

[KennethHoff]

For completeness sake; you went with option 1, right?

[captainsafia]

For completeness sake; you went with option 1, right?

Correct. I added a remark to the API that it's only compatible with Swashbuckle.AspNetCore.

aspnetcore/src/OpenApi/src/Extensions/OpenApiEndpointConventionBuilderExtensions.cs

Lines 27 to 30 in 0e4ccd1

	/// <remarks>
	/// This method does not integrate with built-in OpenAPI document generation support in ASP.NET Core
	/// and is primarily intended for consumption along-side Swashbuckle.AspNetCore.
	/// </remarks>

NSwag hasn't added support for WithOpenApi (see RicoSuter/NSwag#4163).