NSwag v14 preview announcement & breaking changes #4524
Comments
|
Hi, The 14.0.0-preview004 package for NSwag.ApiDescription.Client seems to have a dependency of and when I try to update in Visual Studio it complains because NSwag.MSBuild only has 14.0.0-preview00N packages |
|
@Numpsy try v14.0.0-preview005 |
|
Ok, the new version has installed ok |
RicoSuter
changed the title
|
Both .NET Core 3.1 and .NET 5 are out of support already and .NET 8 is around the corner. So maybe drop support for old versions? |
|
@olegd-superoffice there's #4001 for that |
|
fwiw I've dropped the v14 test packages into a project that contains an asp .net core 3.1 web service and a mix of client builds using different .net versions, but one of the reasons for that is that I'm trying to see what's going on with the Mend complaints described at #2824 - and as long as I can generate client code that can build as .NET Standard 2.0 it doesn't matter if the code generator itself needs .NET 6+ and I don't have any pressing need to update the server side itself |
I wonder if this now makes it impossible to generate API specification and clients via MSBuild. Seems that now MSBuild will invoke NSwag's There's also quite a lot of performance penalty from invoking the build pipeline multiple times. EDIT, so the way |
Exactly, if you run this as part of the csproj build (after build) then you need to enable noBuild |
Nit: the docs will eventually need to be updated to reflect this, e.g. WebApiToOpenApiCommand Out of curiosity, what was the reason to remove this feature? I mean, I understand that having fewer commands makes the code easier to maintain. But it feels very sad to have start up the application to generate swagger from it, when it's used at large scale. E.g. the build and prod enviornments might be very different and the app might not start up on the build machine. Or it might do some very expensive intialisation, like read from databases, that might significantly increase build times (if the nswag generation happens during the build). I am aware that I could put all the controllers into a library and have two Asp.Net core apps, one for prod doing the real initialisation, and a "dummy one" just for nswag. But having to do this just feels so painful compared to how easy it was to use NSwag v13. |
Main reason is that all this legacy stuff puts a lot of maintenance effort. The web api generator is still available, so the simplest solution for you would be to just build your own simple CLI tool which uses the
Did you use WebApiToOpenApiCommand for ASP.NET Core? That's a very bad idea as it uses reflection and not the API explorer which might lead to completely wrong results... |
|
Version |
|
Is this a problem? |
|
@RicoSuter we have all other packages (also transitive) in our project updated to the latest version, except this. Is there any blocker not to update this one to latest? |
|
@m-demydiuk This reference is only setting minimal supported version of the package, but you always can use newer ones in your project if you reference the dependency directly of if you use NuGet's central package management with |
|
@RicoSuter Will there also be a preview of the NSwagStudio 14.x ? 😄 |
|
@Herdo the studio setup MSI should now be part of the release assets. |
|
What's about OpenAPI v3.1.0/swagger-ui v5? This is being constantly asked since 2021 in a #3761, but haven't been answered still. Are these a planned features, at least? |
|
In v14 preview |
|
It looks like |
|
@vipwan @chriscameron-vertexinc services.AddSwaggerDocument(document =>
{
document.SchemaSettings.SchemaProcessors.Add(null!);
document.SchemaSettings.UseXmlDocumentation = true;
}); |
|
nswag.json My nswag.json aspNetCoreToOpenApi document generator has the following assembly path: Since following the advice above to set noBuild to true this is working perfectly in VS2022 when I build for Debug or Release. In my CI/CD pipeline I'm doing the following: This also works perfectly from my local command line, however on my build machine I get: It looks like NSwagExe_Net80 isn't replacing the The exact same script, and exact same machine, when working with .net7.0: |
|
@chriscameron-vertexinc assembly path loading has been removed, use “project” with path to csproj instead |
|
JsonSchemaGeneratorSettings Is part of NJsonSchema and now a property and not inheritance anymore.. mainly because there are now two variants: system.text.json and newtonsoft.. |
I've now updated my nswag.json to use project instead of assemblyPaths and I'm seeing the exact same problem. It looks like I misspoke when I said I couldn't reproduce the problem locally. After deleting my bin directories to clear out the Debug output my post build step is failing in VS2022 release builds.
|
|
Sorry, i would really appreivcate a clarification on how we are supposed to work here with the removal of the WebApi2Swagger.
Our current solution was simple, in the SDK, we used WebApi2Swagger to create the openapi In our DLLs (Notice, in the DLL we also exported the document for the SDK counterpart)
am i missing something here? are we working completly wrong? |
|
We had to tune the configuration a bit after enabling {
"runtime": "Net70",
"defaultVariables": null,
"documentGenerator": {
"aspNetCoreToOpenApi": {
"project": null,
"documentName": "v1",
"msBuildProjectExtensionsPath": "../../artifacts/obj/TheProjectFolder",
"configuration": "$(Configuration)", |
|
Thanks so much @lahma ! In summary, I've had to change the following to get NSwagExe_80 to work for me:
|
|
We had to migrate our api from .net7 to .net 8. After migration our typescript client has some issues: Main issue is because we have |
Something like that @vipwan |
|
Seems like the services.AddOpenApiDocument(options =>
{
options.OperationProcessors.Add(new MyOperationProcessor());
});Yet another breaking change that is not documented in any way shape or form. This is why my organisation is moving to Kiota. |
|
UseXmlDocumentation doesn't seem to load XML documentation for other assemblies in V14... Has anyone got this to work? |
|
Upgrade to .NET 8.0 and NSwag.AspNetCore 14.0.3 Exec NSwag exited with code -1. Has anyone any idea how to fix this? My command: My nswag.json |
|
I have upgraded to v14 and the build is failing. Here is configuration I have and it works with v13 |
|
Hello I used to use I am setting it to "documentName": "v2", however this throws the following exception System.InvalidOperationException: No registered OpenAPI/Swagger document found for the document name 'v2'. Add with the AddSwagger()/AddOpenApi() methods in ConfigureServices(). Note that "documentName": "v1", works but generates both v1 and v2, I only want to generate v2. Thanks. |
app.UseSwagger(typeof(WebApiApplication).Assembly, settings => {});This code is not working on the latest version of EDIT: OK, I changed it to |
|
And how to update this code? app.UseSwagger(typeof(WebApiApplication).Assembly, settings => {});
{
settings.GeneratorSettings.SerializerSettings = new JsonSerializerSettings
{
ContractResolver = new CamelCasePropertyNamesContractResolver(),
// Show enums as string, not integers
Converters = { new StringEnumConverter() },
};
});EDIT: Fixed by: RouteTable.Routes.MapOwinPath("swagger", app =>
{
app.UseSwaggerUi(typeof(WebApiApplication).Assembly, settings =>
{
var schemaSettings = new NewtonsoftJsonSchemaGeneratorSettings
{
SerializerSettings = new JsonSerializerSettings
{
ContractResolver = new CamelCasePropertyNamesContractResolver(),
// Show enums as string, not integers
Converters = { new StringEnumConverter() },
},
};
settings.GeneratorSettings.SchemaSettings = schemaSettings;
});
});Now I have runtime exception: .NET Framework v4.8, NSwag v14.0.8 |
|
You might wanna use it this way: if (settings.GeneratorSettings.SchemaSettings is NewtonsoftJsonSchemaGeneratorSettings newtonsoftJsonSchemaGeneratorSettings)
{
...
}To do not drop defaults |
|
Ad runtime error: Are you sure you have all NSwag packages in the same version? Checking the version of the NJsonSchema packages might be a good idea as well. |
|
Instead of ReDoc, you might use |
|
Can I prevent the configuration file from being overwritten by NSwag on build?
|
|
Thanks @trejjam Runtime exception was fixed by changing
My Now I can open Swagger - it is also showing v1 and v2 endpoints :) But JSON settings are not working :( if (settings.GeneratorSettings.SchemaSettings is NewtonsoftJsonSchemaGeneratorSettings newtonsoftSettings)
{
newtonsoftSettings.SerializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver();
// Show enums as string, not integers
newtonsoftSettings.SerializerSettings.Converters = [new StringEnumConverter()];
}
|
|
NSwag is transitioning to You can check (by debugger) if you are using NewtonsoftJsonSchema in Then, you can solve the issues you are having in the library you are using. |
|
I'm using .NET Framework for this project and I don't have |
|
Then, it would be best to look at how it's done for the .Net Framework. I have 0 knowledge of the .Net Framework. |
|
I'm using .NET 8 framework and have NSwag.AspNetCore v14.0.8 installed. When I startup my application, I'm receiving the follow message: The exception is thrown during startup when it hits the following code: Here is my stacktrace: Does anyone have suggestions on how to remediate this? Let me know what else I can provide. |
|
I think you are mixing Owin and Core integration: |
How would I identify if it is using Owin as opposed to Core? I'm farily certain I am using Core. |
and others
Please test the preview packages for NSwag v14 and NJsonSchema v11 and report problems here.
Note: NSwag/NJS still uses Newtonsoft.Json for serializing/deserializing schemas internally, so for now it still requires newtonsoft as a reference, internal serialization will hopefully migrated to STJ in the next major version.
This whole major version is about dropping old stuff to make the project maintainable again. I'm testing it with my more or less modern ASP.NET Core applications. The goal is that the tooling still works with them and there are no regressions or very hard to mitigate breaking changes.
NSwag v14
PR: #3758
Breaking changes
NJsonSchema v11
PR: RicoSuter/NJsonSchema#1450 (merged)
Breaking changes
Other changes:
The text was updated successfully, but these errors were encountered: