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.
Really liked the talk, I come from other languages and saw that state of things in C# ... it was depressing. I'm curious how to deal with changes to the API without having to override all code, as in: * generate code from spec.yaml * update the controllers to do real work * update the spec to add new function * it overrides all existing endpoints... It'd be awesome if It could figure out that you've implemented already some of the endpoints and would not just override it. Maybe I'm missing something!
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.
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".
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!
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)
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. Oh, and part of the reason for the API spec is precisely to provide a technology agnostic reusable component - as that is both an indication of it being done right and opens up the possibilities of alternative implementations. M$ devs have never sat easy with that statement - until the next version of the M$ tools come out (dot-net-sharp-plus-plus-X-AI) or whatever it'll be called and it has to be written from scratch. The man speaks the truth.
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).
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.
YAML is the Python of JSON
Really liked the talk, I come from other languages and saw that state of things in C# ... it was depressing.
I'm curious how to deal with changes to the API without having to override all code, as in:
* generate code from spec.yaml
* update the controllers to do real work
* update the spec to add new function
* it overrides all existing endpoints...
It'd be awesome if It could figure out that you've implemented already some of the endpoints and would not just override it. Maybe I'm missing something!
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.
Yup - what's their take away from the talk? - "let's have an argument about the pros and cons of YAML " - so missing the point that it hurts.
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.
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".
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...
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.
🤣
Oh Hi Mark
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.
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.
Oh, and part of the reason for the API spec is precisely to provide a technology agnostic reusable component - as that is both an indication of it being done right and opens up the possibilities of alternative implementations. M$ devs have never sat easy with that statement - until the next version of the M$ tools come out (dot-net-sharp-plus-plus-X-AI) or whatever it'll be called and it has to be written from scratch.
The man speaks the truth.
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.