Skip to content

@RicoSuter RicoSuter released this Nov 16, 2018

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.


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


  • 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)

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
    • 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
      • 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

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)


  • 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)


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


Assets 4
You can’t perform that action at this time.