Split up the generated OpenApi file into multiple files

[klacol]

We generate our OpenApi files (2.0 and 3.0) from our ASP.NET Controllers, as described here. That works like a charm.

Since our models are quite big, this takes a while (about 1 second for generating the Json file and about 7 seconds to render it in the Swagger UI).

We have tested with ReDoc directly. There, the API-specification file is splitted up into several smaller files. They live in subfolder to the specification files (structured in definitions and paths). This results in a more modular structure, and the loading time is shorter.

You can see that in this repo: https://github.com/Rebilly/RebillyAPI

Does NSwag have the possiblity to generate the OpenAPI-file splittet up in subfolders and referenced files?

[RicoSuter]

No this feature is not yet supported. Basic file $refs work but when serialized back you’ll end up with an unified document.

This feature would need quite some work in order to have a good file abstraction and correct reference resolution when serializing...

[klacol]

Thanks for this clarification.

In our case, this would only be one-way (Serialize C# to Json) , only to be able to have the HTML docs. A deserialization would not be needed.

[RicoSuter]

Sorry, i meant serialization (updated). How would this look like? A file per dto schema and also per operation?

[klacol]

Indeed, the terms for serialization and deserialization can be confusing in this situation.

Yes, a file per dto schema and also per operation (path) would be good. We have done a manual sample here.

Instead of writing a single file, one could write the NSwag.SwaggerDocument to a folder or provide it as a ZIP file in a defined folder structure.

[maikebing]

So, are there any options available or have this plan in the future?

[RicoSuter]

Indeed, you could generate multiple files from one SwaggerDocument, but you’d need to replace the refs with external refs, etc. hard to tell how much effort this is and whether you will be able to read specs which reference json schemas and not other swagger specs

Will work on issues with higher prio first...

[syndicatedshannon]

see #1398 for splitting generated code.

although more granular revisions history for large APIs would certainly be beneficial, I'm more concerned about the code splitting than contract splitting.