MK.NET - Mark Rendle - OpenAPI: You're Doing It Wrong

The Talk

.NET developers have two options when it comes to OpenAPI or Swagger: Swashbuckle and NSwag. Just decorate your controllers or minimal API endpoints with a bunch of attributes and a NuGet package will generate the swagger.json file for you, right?

No. Wrong. That's not how this is supposed to work.

In this talk, Mark will try to convince you that the correct way to implement OpenAPI is to write and maintain that file manually. Probably as YAML instead of JSON. That way it's included in your version control history, you can use it to generate Markdown docs in a GitHub action, and people don't need to run your app to get a copy of the file.

Mark is working on some new NuGet packages that will provide some pretty neat functionality for static OpenAPI files, including serving a YAML file as JSON in your application, analyzing your code and checking that it matches the spec, and maybe some automated testing as well.

About Mark

Mark Rendle is the founder of RendleLabs, which is really just him playing with .NET Core, Docker, Azure, microservices and so on and then teaching other people about it and helping them build clean, stable, scalable solutions. He's been getting paid to do what he loves for nearly 30 years now, and still worries that somebody's going to notice and make him stop. He's on Twitter @markrendle.