OpenAPI & .NET: You're Doing It Wrong - Mark Rendle - NDC London 2023

Подписаться 194 тыс.

Просмотров 15 тыс.

50% 1

.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/

Наука

Опубликовано:

5 июн 2023

Ссылка:

Скачать:

Готовим ссылку...

Добавить в:

Мой плейлист

Посмотреть позже

Комментарии : 30

@TreeLuvBurdpu Год назад

YAML is the Python of JSON

@JamesHarrisonHaribo Год назад

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.

@ouvreboite87 5 месяцев назад

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.

@ViktorFerenczi Год назад

Completely agree about Atlassian tools.

@JeffryGonzalezHt Год назад

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.

@alexanderpodkopaev6691 11 месяцев назад

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

@christian123542 8 месяцев назад

You could also just implement a dummy method into some controller that just returns a dummy status code. Has exactly the same effect.

@kabal911 Год назад

I’ll stick with auto generated with Nswag, AND committing to version control.

@zenluiz Год назад

How to have a repo with generic schemas/components and reference them in other repos?

@marijnstapert9036 5 месяцев назад

Build an artifact and publish it to a repository (nuget, npm, mvn w/e)

@dogstar9455 4 месяца назад

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".

@KangoV 9 месяцев назад

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!

@Zainjerr 5 дней назад

Oh Hi Mark

@sizur Год назад

Arguing that expressive static checks is wrong and either cowboy text or hand-rolled custom buggy validators is the right way. . . ok...

@simongeering Год назад

Ok but would I rather write c# or yaml 😮

@ks1970in Год назад

Of course C#.

@ShadoFXPerino Год назад

Next talk you'll tell us that Code-First EF Core is worse than Database-First EntityFramework 6.

@ks1970in Год назад

🤣

@XXnickles Год назад

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)

@snake3837 4 месяца назад

You know that the only point of OpenAPI is for generators? Why even bother using it if you would not generate anything from that.

@snake3837 4 месяца назад

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.

@outwithrealitytoo Месяц назад

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.

@outwithrealitytoo Месяц назад

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.

@MoskowGoAwayFromUa Год назад

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.

@GeorgeTsiros Год назад

I LOVE SEMANTICALLY SIGNIFICANT WHITESPACE IT IS THE BEST

@ks1970in Год назад

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).

@GeorgeTsiros Год назад

i have no idea what he is doing. Is he trolling us? He doesn't _look_ drunk