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

#5395 · closed · 1 comments

View on GitHub ↗

WoehlerDanielWecker

**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.

Comments

WoehlerDanielWecker

I've since figured out that you don't necessarily have to include a local copy of the Swagger JSON in the nswag file to generate the client. If you simply leave the “json” field blank, you won't run into problems with the high number of AI tokens when generating commit messages. So, excuse me for this unnecessary request. With the above insight, it's obviously no longer required. I'm closing this issue.