OpenAPI & .NET: You're Doing It Wrong - Mark Rendle - NDC London 2023
Вставка
- Опубліковано 5 чер 2023
- .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 SwaggerUI and beautiful documentation with code samples, generating application and test stubs, validating your implementation against the spec, and more.
Check out our new channel:
NDC Clips:
@ndcclips
Check out more of our featured speakers and talks at
ndcconferences.com/
ndclondon.com/
![Lp. Последняя Реальность #107 РОДНОЙ ДОМ [Финал] • Майнкрафт](http://i.ytimg.com/vi/IK3QKzKUlHM/mqdefault.jpg)
Just going to say, I’ve used the YAML first approach, and I hated it oh so much. Even with request/response validators you can still make errors when doing it by hand. And client generators so often don’t cover all parts of the OpenAPI spec. The c# first approach almost always makes good yaml output, and client code generators typically like what it outputs.
YAML is the Python of JSON
Completely agree about Atlassian tools.
Polymorphic POST? Holy cow, you've just re-invented SOAP! This stuff is a struggle for sure, but I think where I've landed is that if an entity is shared across multiple services we just define it elsewhere and give it a "formal" media type (eg: Content-Type: application/company-vehicle+json and don't define those in our OpenAPI spec, but elsewhere. What I'd love is the ability to autogenerate, and do a form of snapshot testing - so if I do something that would be a breaking change from an earlier version, it'd inform me.
I write yaml simply because I don't want front-end developer to sit waiting for backend write first version and generate small incomplete swagger
How to have a repo with generic schemas/components and reference them in other repos?
Oh Hi Mark
I’ll stick with auto generated with Nswag, AND committing to version control.
The openAPI file cannot cover everything needed for a full blown spec correct? Meaning, There is other data mapping information and business logic needed to be written somewhere that explains HOW to populate the fields/objects. Is this built into openAPI and I'm just missing it? If I have a "clownName" field, I may need to explain that this is populated using a completely separate openAPI, in an object called "circus employees".
This whole comment section is a testament that nothing changed for .net "devs" for the last 20 years 😂 Good I quit, it was hard to find decent job.
When dealing with lists, the generators have loads of errors! Well, they do in Java anyway. These bugs have been around for quite a while. You have been warned!
Arguing that expressive static checks is wrong and either cowboy text or hand-rolled custom buggy validators is the right way. . . ok...
Ok but would I rather write c# or yaml 😮
Next talk you'll tell us that Code-First EF Core is worse than Database-First EntityFramework 6.
Funny... this generating your API spec from the code is like generating database schemas from an ORM... "I don't understand SQL and databases well enough, so I'll write some code and hope the computer will dis-ambiguate, complete and optimise my requirements" - that ended badly. With APIs this cart before the horse approach will end badly as well. What will the next generation do? "Let's throw the problem at ChatGPT!" Without any discernment that will end up in exactly the same place - with barely functioning software in the smoldering ruin of a late project, with no reusable components.
All good...until you mix generators in the mix and then you have a nice piece of who-knows-what. Nah, I am sticking to using open API as reference for others. If they decide they want to punish themselves with generators, more power to them! The main issue here is, paradoxically, HTTP. You can interpretate the "standard" in the way you want, and that is a source of bunch of problems (starting to call anything that use HTTP + JSON as REST for example)
I LOVE SEMANTICALLY SIGNIFICANT WHITESPACE IT IS THE BEST
Reading output types in yaml is horrible. It is so redundant. As a result big files. No types, everything is object. A lot of information garbage.
Do not agree with arguments at several levels.
YAML - vs adding a couple of attributes onto an endpoint in code? ... Yeah, I'll stick with attributes and confirm - YOU are doing it wrong.