rducom
commented
6 years ago Improved OpenAPI specification support
We want to embrace the OpenAPI specification (previously called “Swagger”) and make Web APIs built with ASP.NET Core more descriptive. Today you need a lot of “attribute soup” to get a reasonable OpenAPI spec from ASP.NET Core. We plan to introduce an opinionated layer that infers the possible responses based on what you’re likely to have done with your actions (attributes still win when you want to be explicit).
For example, actions that return IActionResult need to be attributed to indicate the return type so that the schema of the response body can be determined. Actions that return the response type directly don’t need to be attributed, but then you lose the flexibility to return any action result.
We will introduce a new ActionResult
type that allows you to return either the response type or any action result, while still indicating the response type.
Détails : https://joonasw.net/view/aspnet-core-2-1-actionresult-of-t
Soit on garde le format API v3 actuel, en complément d'un format Swagger ou autre, soit on part sur un de ces standard et on abandonne complètement notre format.
Même si je sais qu'un développeur préfère utiliser un outil plutôt que de s'en forger un lui-même, je ne suis pas hyper chaud pour abandonner le contrôle sur notre format. Donc je serais plus pour un mix custom/swagger par ex. Ca permet d'y aller en douceur, et si on voit via les premiers projets à basculer en Swagger que c'est vraiment swag, ben on convertira tous les autres.
Il faut regarder OpenApi qui a l'air de répondre au besoin tout en proposant du Swagger (c'est complémentaire plus que concurrent visiblement).