#5395·NSwag

NSwag Studio: Option to store downloaded OpenAPI specification externally instead of embedding it in *.nswag file

Author: WoehlerDanielWeckerCreated Aug 10, 2026Updated Aug 10, 2026

Is your feature request related to a problem? Please describe. When NSwag Studio downloads an OpenAPI/Swagger specification from a specification URL, it stores the full JSON inside the .nswag file at documentGenerator.fromDocument.json.

Functionally this works, but in practice it creates very noisy diffs because the downloaded specification is effectively stored as one large inline JSON value. Even small changes in the source specification can therefore show up as a very large one-line change in the .nswag file.

In our workflow this is especially problematic because our projects are stored in Git repositories and we increasingly use AI-based tooling, for example for commit message generation or repository analysis. Since the diff is not granular, these tools have to process a lot of unnecessary text, which increases token usage significantly. It also makes .nswag files larger and harder to review.

Describe the solution you'd like I would like NSwag Studio to optionally support storing the downloaded specification in an external file instead of embedding it directly into the .nswag file.

That external file could then be ignored via .gitignore if desired. In many cases this would not really mean losing important information in version control, because the generated code already reflects the relevant changes introduced by the updated specification.

Additionally, or as a simpler first step, it would already help if the embedded JSON were written in a formatted / indented way so Git diffs become more granular and readable.

Describe alternatives you've considered A possible alternative would be to keep the current behavior but format the embedded JSON instead of storing it as a single long line. That would already improve Git diffs and reduce the amount of irrelevant text that AI-based tools need to process.

Another workaround is to accept the current behavior and live with the noisy diffs, but this becomes increasingly inconvenient in repositories where .nswag files are updated regularly.

Additional context Besides reducing noisy diffs and AI token consumption, this would also help keep .nswag files smaller and easier to maintain.