Encourage your API designers to use this approach to not only add documentation in the main body of an API design, but also in any libraries you use. There’s a lot to like in Cadl.

About Swagger Swagger is an open source API framework, sponsored by SmartBear Software, that allows developers and teams to design, build, document and consume RESTful web services.