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 also relied on the now removed approach (WebApiToOpenApiCommand). So now looking for a workaround. So it is still going to be around for a while although being marked as deprecated for dotnet core?
We ran into this when upgrading to dotnet 8 and had to update nswag. |
|
You can get a clue what went wrong by executing |
|
We are currently facing inconsistent output where keys are:
This is unexpected, feels like a bug could also be a missing configuration 😅 Any hints are much appreciated 🙏 Snippet of the generated `swagger.json` via controllers: "CreateUserCommand": {
"type": "object",
"additionalProperties": false,
"properties": {
"tenantId": {
"$ref": "#/components/schemas/TenantId"
},
"email": {
"type": "string"
},
"userRole": {
"$ref": "#/components/schemas/UserRole"
}
}
},Snippet of the generated `swagger.json` via CLI tool: "CreateUserCommand": {
"type": "object",
"additionalProperties": false,
"properties": {
"TenantId": {
"$ref": "#/components/schemas/TenantId"
},
"Email": {
"type": "string"
},
"UserRole": {
"$ref": "#/components/schemas/UserRole"
}
}
},References to code: (we are using .Net 8 Minimal Api's in PlatformPlatform and referenced code is from a WIP Pull-Request) |
|
Something like this should help you :) public static class OpenApiDocumentGeneratorSettingsExtensions
{
public static void ConfigureSchemaSettings(
this AspNetCoreOpenApiDocumentGeneratorSettings settings, IServiceProvider serviceProvider
)
{
if (settings.SchemaSettings is SystemTextJsonSchemaGeneratorSettings systemTextJsonSchemaGeneratorSettings)
{
var originalJsonOptions = serviceProvider.GetRequiredService<IOptions<JsonOptions>>().Value.SerializerOptions;
var jsonOptions = new JsonSerializerOptions(originalJsonOptions);
jsonOptions.Converters.Add(new JsonStringEnumConverter());
systemTextJsonSchemaGeneratorSettings.SerializerOptions = jsonOptions;
}
}
}
IServiceCollection.AddOpenApiDocument((settings, serviceProvider) => settings.ConfigureSchemaSettings(serviceProvider)); |
|
Thanks! @trejjam for the quick reply, that fixed the issue 🎉 |
|
I recently updated to NSwag v14.0.1 and noticed that the "classNames" feature in the "typesToOpenApi" configuration has been removed. I have specific models, like "MyClassDto," that I need to include in the generated TypeScript code. I am seeking guidance on how to replace the "classNames" configuration in the latest version. I need to include only certain C# models in the TypeScript output. How can I achieve this with the latest version of NSwag? |
|
Just adding a note here in case it helps someone else. While upgrading to .NET 8 and NSwag 14, we ran into errors while building trying to use the NSwag command line tools with the aspnetcore2swagger option which has been removed. With .NET 7 and NSwag 13.20, we used this in our csproj files: With .NET 8 and NSwag 14.0.1, we had to change this to: Also, in our Program.cs file, we had to change |
|
I have many many projects that used reflection on .NetFramework, so I created this "wrapper" nuget package that kinda provide a similar CLI experience to generate the specs. It uses but does not replace NSwag. https://github.com/valadas/WebApiToOpenApiReflector |
|
After Updating to Net8 with migrate NSwag 13.20.0.0 (NJsonSchema v10.9.0.0) to v14.0.2.0 (NJsonSchema v11.0.0.0). Updates in Generated service-proxies.ts using the NSwag toolchain v14.0.2.0 (NJsonSchema v11.0.0.0 (Newtonsoft.Json v13.0.0.0)): changed to changed to changed to: any ideas how to fix this? |
I'm having the same issue. Our type definitions live in model libraries rather than asp net core services directly. Good practice I believe. How do we generate types from a library build now? |
|
After I migrated to .net 8, I changed the generation of the swagger file to be project-based Locally, it works wonderfully. However, the project cannot be found or assigned in the build process in the Azure DevOps pipeline. See error message: Update 02/05/2024 |
I have the same issue in another context. |
|
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. |
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: