Changing the Order of Parameters in Swagger / OpenAPI Documents when using NSwag to Generate the Swaggerfile

Georg Dangl by Georg Dangl in Web Development Sunday, April 16, 2023

Sunday, April 16, 2023

Posted in Asp.Net Core

Our AVACloud SaaS product has been available for a few years already. While that's a great achievement in itself, it also comes with drawbacks: The API is used by a lot of customers by now, which requires us to keep it stable and not introduce breaking changes or incompatibilities with existing implementations. Move fast still applies, but the break things part would now be a problem.

So, we've recently updated one endpoint to support additional parameters. It's a simple REST endpoint that takes a file, some options, and does a conversion. In the.NET backend, the controller receives three parameters: The file, and two options objects for the import respectively export configuration. That maps nicely, and introducing additional parameters is as easy as adding a new property to a view model used for the bindings. Many clients generated via Swagger can follow the same approach of using options objects for the client interface, thus no problem there.

However, the objects are transported as query parameters. This means that from a Swagger perspective, we've now added two new query parameters. This can cause problems when the new parameters are not sorted to the end, thus generating a new client version would break existing implementations and require attention and a rewrite from every consumer of the API.

Luckily, we're using NSwag in the backend, which allows a great deal of customization. When we set up Swagger generation, we can simply inject custom code in the PostProcess callback and sort the parameters however we want.

We're just getting the current parameters, apply our custom sort logic which ensures the new parameters are at the end, and then clear and refill the parameter list.

There are other options available, such as using custom x-position attributes, but I've found that relying on such non-standard features often causes problems later with some client generators. So, let's keep it simple and stupid😀

Happy customizing!

Share this post

comments powered by Disqus

About me

Hi, my name's George! I love coding and blogging about it. I focus on all things around .Net, Web Development and DevOps.


Need a consultant for BIM, GAEB or Software Development?

Contact me at [email protected], +49 (173) 56 45 689 or visit my professional page!

// Just 💗 Coding

Social Links