RicoSuter/NSwag NSwag-Build-1032

NSwag v12.0.0 (Build 1032)

on GitHub

Discussion and issues

Breaking changes and issues:

There are breaking changes but most of them can be easily fixed by using the renamed method or change a setting.

NSwagStudio

• If you get a "YamlDotNet.Signed DLL not found" exception, try uninstalling and reinstalling NSwagStudio, #1750

Settings

• The default settings have been updated, see PR #1719 for details
  • When using an nswag.json file, the old settings are retained and this is not a breaking change.
  • When using the CLI directly (e.g. swagger2csharp command) then these defaults may be a breaking change and the previous settings have to be set explicitely to generate the previous output.

Runtime (CLI, NPM, NSwagStudio)

• Default runtime set to NetCore21 (before WinX64)
  • Change this in NPM command line with the /runtime:WinX64 parameter
  • The WinX86/WinX64 command line ASP.NET Core dependencies have been upgraded to 2.1.x (#1696)
  • Upgrade ASP.NET Core dependencies (x64/x86) (#1696)
  • For more information, see https://github.com/RSuter/NSwag/wiki/Assembly-loading

NSwag.AspNetCore (middlewares)

• The API of the ASP.NET Core middlewares have been changed (easy fix)
  • All public and not obsolete methods are now completely based on AspNetCoreToSwaggerGenerator
    • The old WebApiToSwaggerGenerator based methods are still available but deprecated and will be removed in v13 (#1700)
  • AddSwaggerDocument()/AddOpenApiDocument()
    • Document configuration moved to AddSwaggerDocument(configure) in ConfigureServices() (before in UseSwaggerWithApiExplorer())
  • UseSwaggger()
    • UseSwagggerWithApiExplorer() is now just UseSwagger() in Configure()
    • SwaggerRoute renamed to Path (#1728)
  • UseSwaggerUi*()
    • Web UI methods now only register the UI and do not serve swagger.json anymore (use an additional call to UseSwagger())
    • UseSwaggerUi3WithApiExplorer() no longer exists, use UseSwagger() and UseSwaggerUi3() in Configure()
    • UseSwaggerReDoc() renamed to UseReDoc()
    • SwaggerUiRoute renamed to Path (#1728)
    • SwaggerRoute renamed to DocumentPath (#1728)
  • For more information, see PR #1655 and wiki at https://github.com/RSuter/NSwag/wiki/AspNetCore-Middleware
    • Use AddOpenApiDocument()/AddSwaggerDocument() directly on services (#1714)
    • Add IDocumentProvider service and its implementation (#1678)
      • This is used in the CLI with the new UseDocumentProvider setting (enabled by default)
• API Versioning handling has been improved with breaking changes
  • The ApiVersionProcessor registration and IncludedVersions have been removed and replaced by the ApiGroupNames setting
    • For more information see PR #1701 or wiki at https://github.com/RSuter/NSwag/wiki/AspNetCore-Middleware
    • Add ApiGroupNames setting, remove ApiVersionProcessor and improve api versioning (#1701)

Bug fixes and improvements

Swagger generator

• Add CreateWebHostBuilderMethod and AspNetCoreEnvironment setting, implement UseDocumentProvider & DocumentName #1655
  • UseDocumentProvider will be enabled by default and generates a document registered with AddSwaggerDocument() in ConfigureServices
    • Select document with the DocumentName setting
  • CreateWebHostBuilderMethod can be used to define the CreateWebHostBuilder method (entry point to load an app)
  • AspNetCoreEnvironment changes the ASPNETCORE_ENVIRONMENT env var
• Use SwaggerResponseAttribute.Description with API Explorer, closes #1648
• Add TransformToExternalPath setting (#1728)

CSharp

• Use header parse, closes #1649
• Handle OpenAPI 3 file response in client generators, closes #1629
• [C# Client] Boolean query parameters are now lowercase (#1711)
• Add support for x-www-form-urlencoded (CSharp) (#1739)

TypeScript

• Fix default reponse handling (TS), closes #1683
• Only generate the blobToText and throwException if it is needed (#1705)

Other

• Change YAML version to v5.0.1, 1e2baa5
• Rename TagSorter -> TagsSorter to match what swagger-ui needs (#1708)
• Fix swagger ui 3 params, closes #1694
• Use correct operation type, closes #1650
• Migrate some test projects to use Xunit (#1669)
• All changes & fixes in NJsonSchema after 9.11.0
  • Add support for JsonInheritanceAttribute in schema generator (RicoSuter/NJsonSchema#813)
  • Add JsonSchemaFlattenAttribute (RicoSuter/NJsonSchema@c1484a0)
  • Dereference actual type schema (RicoSuter/NJsonSchema#798)