suggestion: add openapi utilities (or add in examples)
Closed this issue · 4 comments
Awesome library, not using your lib in this example, but was just thinking maybe also it could benefid from some quick functional openapi utility functions?
would be greate if at leat all "extension methods" could be instead functional pipelines..
|> withName ""
|> withOpenApi
seems openapi reg is not very "functional" but ofc it should work fine with this on endpoint routing (adding 2 packages as dependencies
https://learn.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis/openapi?view=aspnetcore-8.0
Thank you for suggestion! I've actually thought about openApi, you can check it out here: https://github.com/Lanayx/Oxpecker/blob/openApi/examples/OpenApi/Program.fs (just adding 2 packages doesn't work, so manual api description is needed). However I stopped there, because I figured out that the proper way would be to generate server stub base on schema (similar to https://github.com/Szer/GiraffeGenerator) and not the opposite. So, I'm not sure if I need to merge openApi example into develop branch, since it looks quit hacky.
I think that if we are to improve the server-first approach (make it production ready), then at least some reflection based generation to OpenApiComponent should be implemented first.
i think maybe is not reflection based not sure, as minimal api now is oriented to AOT, so i suppose there shouldnt be too much reflection, this why is added via builder explicitly for C# code? i would try to follow also what aspnet does by deafault, i think giving Openapi/swagger pages to devs is a good default,
API first or code first, i think both should work. most developers first code then write the contract (though is not the best practice, is easier, as knowldge of openapi specs often changes and formats chnage as well)
Mimimal API can be used by using Delegate or RequestDelegate. The former allows OpenApi generation by using C# source generators, while the latter doesn't. However it's also slower and less type-safe and DX is not good with F#, so Oxpecker (and Falco) use the second option - HttpContext -> Task function. So, to use code first generation it should be reflection-based approach or it can also be AOT approach with myriad and fantomas, but with manual definition to which types to generate. At the same time it will be quite limited, it really reminds me EntityFramework experience - it works well on demos, but in big real projects where fine-grained control is needed it will bring more problems than it solves.
At the same time schema-first approach is much cleaner - schema can be as fine-grained as needed. So I think that if someone wanted to invest time in openAPI integration with Oxpecker, this would be a more productive way to spend time on.
An update :) As soon as it appeared to be possible to reuse built-in OpenApi generation with low effort it was added as Oxpecker.OpenApi package. I still think that schema-first approach works better for big projects, but for small ones with a tight time schedule ability to quickly generate is indeed useful, hence the package was born.
With that I'm closing current ticket, any other issues of the implementation can be raised in separate tickets.