Using WithSummary() for Minimal API endpoints does not render when using Swashbuckle.AspNetCore

[martincostello]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

Using the new WithSummary() method (or [EndpointSummary] attribute) on a Minimal API endpoint in ASP.NET Core Core 7 preview 2 does not render the summary in the OpenAPI document generated by Swashbuckle.AspNetCore.

I figure this is because Swashbuckle.AspNetCore would need changes to consume the new metadata to use and output it, but as I thought I'd raise this for visibility as I couldn't immediately see anything in the backlog related to this and because #37906 is closed which seems to imply it should "just work™️".

Using SwaggerOperationAttribute

Using WithSummary()

Expected Behavior

The string passed to the WithSummary() method of [EndpointSummary] attribute is rendered in the OpenAPI JSON document generated by Swashbuckle.AspNetCore.

Steps To Reproduce

Clone martincostello/api@66fbf8e, run the application, and navigate to the /docs URL in a browser.

Exceptions (if any)

N/A

.NET Version

7.0.100-preview.2.22153.17

Anything else?

N/A

[ghost]

Thanks for contacting us.

We're moving this issue to the .NET 7 Planning milestone for future evaluation / consideration. We would like to keep this around to collect more feedback, which can help us with prioritizing this work. We will re-evaluate this issue, during our next planning meeting(s).
If we later determine, that the issue has no community involvement, or it's very rare and low-impact issue, we will close it - so that the team can focus on more important and high impact issues.
To learn more about what to expect next and how this issue will be handled you can read more about our triage process here.

[hwoodiwiss]

I'd interested in picking this up if that's alright?

[captainsafia]

@hwoodiwiss Absolutely! The changes will need to happen in the Swashbuckle repo but happy to provide guidance here.

[hwoodiwiss]

Would this be a good opportunity to provide general support for the new I..Metadata Interfaces from Miscrosoft.AspNetCore.Http.Metadata interfaces in Swashbuckle? as the Attributes produced by the WithX extensions implement these.

[captainsafia]

Would this be a good opportunity to provide general support for the new I..Metadata Interfaces from Miscrosoft.AspNetCore.Http.Metadata interfaces in Swashbuckle? as the Attributes produced by the WithX extensions implement these.

We've generally gone for the approach of adding individual support for each of the new types that were added (see here and here).

Moving forward, we'll be relying on the Micorosft.OpenAPI stuff for annotating this stuff directly (see this).

[hwoodiwiss]

Would this be a good opportunity to provide general support for the new I..Metadata Interfaces from Miscrosoft.AspNetCore.Http.Metadata interfaces in Swashbuckle? as the Attributes produced by the WithX extensions implement these.

We've generally gone for the approach of adding individual support for each of the new types that were added (see here and here).

Moving forward, we'll be relying on the Micorosft.OpenAPI stuff for annotating this stuff directly (see this).

Oh interesting, yeah, I can see that rendering any changes I make obsolete fairly quickly.

I've made a "first-pass" implementation over here: https://github.com/hwoodiwiss/Swashbuckle.AspNetCore/tree/hwoodiwiss/asp7-endpointsummarymetadata however this doesn't inlcude the changes for CI that would bee necessary for a PR.

What's the plan with the WithX style functions?
It seems to me that it would make sense for them to act as a bit of a builder(-ish) for an OpenApiOperation and then that object would be available in the endpoint metadata?

[captainsafia]

It seems to me that it would make sense for them to act as a bit of a builder(-ish) for an OpenApiOperation and then that object would be available in the endpoint metadata?

Yep, the existing WithX methods will remain but in the future we'll be adopting the WithApiDescription for modifying any parts of the API.

[hwoodiwiss]

Ah that makes sense.

Given that this has been merged, is there any need to explicitly support the individual metadata types in Swashbuckle, or is the advice going forward to use WithOpenApi with them to have them populate the generated OpenApiOperation, which will then be picked up by Swashbuckle?

[captainsafia]

is there any need to explicitly support the individual metadata types in Swashbuckle, or is the advice going forward to use WithOpenApi with them to have them populate the generated OpenApiOperation, which will then be picked up by Swashbuckle?

Since the summary and description attributes have already been merged and released, I think it is still worthwhile to merge in support for the metadata in Swashbuckle!

[hwoodiwiss]

Okie doke, that makes sense, it'll still be nice to be able to supplement info provided using the Swashbuckle attributes without generating the whole OpenApiOperation as endpoint metadata.

I'll open the PR over in the Swashbuckle Repo at some point this week. Due to the changes to CI that will be required, it may have to wait until a bit closer to .NET 7's Release before it gets merged.

[dotnetspark]

Hi, I am using the latest .NET 7 preview and this is still an issue. I cannot display summary, description, nor produces. Is there any update on this?

[hwoodiwiss]

Hi, I am using the latest .NET 7 preview and this is still an issue. I cannot display summary, description, nor produces. Is there any update on this?

Yeah, there's a PR open with the fix here: domaindrivendev/Swashbuckle.AspNetCore#2414 but it hasn't been merged yet. I'll be looking to get it reviewed and merged when the first RC for .NET 7 is released.

[captainsafia]

Howdy folks!

I'm going to close this issue for now since it is external to ASP.NET Core (Swashbuckle needs to pick up the ISummaryMetadata attributes).

Furthermore, for the long term, we are recommending that folks leverage the new WithOpenApi to modify the summary and other aspects of the OpenApiOperation.

app.MapGet("", () => ..)
  .WithOpenApi(o => {
    o.Summary = "Summary";
  });

Edit: you need to use the latest version of Swashbuckle to light up this feature E2E.

[dotnetspark]

Thanks @captainsafia for the help today.