OpenAPI & .NET: You're Doing It Wrong - Mark Rendle - NDC London 2023
Vložit
- čas přidán 5. 06. 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/ - Věda a technologie
YAML is the Python of JSON
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.
To be fair, even with code-first you can have errors. For example, nothing prevents you from putting the incorrect type in the [ProduceResponseType] attribute. You could even document the incorrect status code. Serialization settings can also introduce mismatch.
Completely agree about Atlassian tools.
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".
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
You could also just implement a dummy method into some controller that just returns a dummy status code. Has exactly the same effect.
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.
How to have a repo with generic schemas/components and reference them in other repos?
Build an artifact and publish it to a repository (nuget, npm, mvn w/e)
I’ll stick with auto generated with Nswag, AND committing to version control.
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...
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.
Ok but would I rather write c# or yaml 😮
Of course C#.
Next talk you'll tell us that Code-First EF Core is worse than Database-First EntityFramework 6.
🤣
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)
You know that the only point of OpenAPI is for generators? Why even bother using it if you would not generate anything from that.
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.
While reading to get a valueable information you have to read many lines, parse them, extract only valuable things.
Supporting yaml files for a big api is another story.
I suppose the next step will be writing yaml in notepad.
Do not agree with arguments at several levels.
- asking for "separate design from implementation" which is good, but when have you had full specs and then design properly completely baked in when a project starts.
- asking for coding in a yaml "because everyone uses it" - that is how we got craploads of XML, rather than treating it as a serialisation tech.
- why do you want to get out of strongly typed land into stringly typed error-prone marshland
- interfaces in C# (or Java or any other programming language) are quite rich, producing a yaml file is just one step more (and if one was desperate, they could produce IDL !!)
Stick to tools that a well designed language gives you. Technology at "edges" (HTTP or gRPC, or COM, or CORBA, or some other kind of RPC or even messaging) can be handled just at outer layer (a la clean architecture).
i have no idea what he is doing. Is he trolling us? He doesn't _look_ drunk
Did you miss the part where he said *everyone* else in the entire tech industry uses OpenAPI?
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.