search

domaindrivendev / Swashbuckle.AspNetCore

Swagger tools for documenting API's built on ASP.NET Core
MIT License
5.17k stars 1.29k forks source link

Update ASP.NET Core documentation for 6.6.1 release #2857

Open martincostello opened 1 month ago

martincostello commented 1 month ago

Raise a pull request to edit getting-started-with-swashbuckle.md once Swashbuckle.AspNetCore 6.6.1 is released to:

  1. Remove the banner stating that .NET 8 is not supported.
  2. Remove the reference to #1920.

See https://github.com/dotnet/AspNetCore.Docs/issues/32477#issuecomment-2099910191.

captainsafia commented 1 month ago

@martincostello Thoughts on updating the templates in 8.0 as well?

martincostello commented 1 month ago

@captainsafia Do you mean the versions referenced by the templates in dotnet/aspnetcore? If so I'm happy to do that if that meets the backport bar.

captainsafia commented 1 month ago

@captainsafia Do you mean the versions referenced by the templates in dotnet/aspnetcore? If so I'm happy to do that if that meets the backport bar.

Yep, that's what I meant. I think we can make the case for it given that .NET 8 is LTS and the lack of support for net8.0 in 6.5.0 is a blocker for build-time doc gen.

martincostello commented 1 month ago

OK cool - I'll do a PR for that tomorrow 👍

cremor commented 1 month ago

Maybe wait with the template update until 6.6.2 is released? Or even a bit longer to give people the chance to test the new version and report bugs.

captainsafia commented 1 month ago

Maybe wait with the template update until 6.6.2 is released? Or even a bit longer to give people the chance to test the new version and report bugs.

Good point! Given the volume of changes that were merged over the past few weeks, it might be good to give things more bake time.

cremor commented 1 month ago

Thoughts on updating the templates in 8.0 as well?

Is this actually feasible? I've just learned that no template changes for existing major .NET versions can be shipped without a "patching request" path and adding features/bumping versions would not meet the bar of value vs risk. Source: https://github.com/dotnet/test-templates/issues/388#issuecomment-2117461282

And .NET 9 templates will not include Swashbuckle at all (see dotnet/aspnetcore#54599).

martincostello commented 1 month ago

It is yes feasible, yes - that's specifically what I already asked Safia already: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/2857#issuecomment-2110754418.

If a member of the .NET team thinks it's a good idea, then it's at least worth opening a PR as presumably they would support the PR getting approved by their process.

And .NET 9 templates will not include Swashbuckle at all

We know this - but this is a conversation about .NET 8, which is supported until November 2026.

martincostello commented 1 month ago

I'll give 6.6.2 a few days to bed-in, then if we don't get any big new issues from 6.6.x I'll do the PR to the release/8.0 branch.

cremor commented 2 weeks ago

6.6.2 looks good and the documentation has already been updated. Will the templates be updated to 6.6.2 or do you want to wait for 6.7.0?

martincostello commented 2 weeks ago

Thanks for the reminder, I'd forgotten about this.

@captainsafia Looking at the release/8.0 branch it seems like the templates are configured to always pull the latest version, so I don't think we actually need to do anything?

cremor commented 2 weeks ago

Isn't this the actual template file? That sets a version, and I think it gets it from here. See also https://github.com/dotnet/aspnetcore/pull/47861

martincostello commented 2 weeks ago

Ah yes - clearly my Visual Studio Code search didn't find that.

martincostello commented 2 weeks ago

https://github.com/dotnet/aspnetcore/pull/56266.