Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
In this PR I propose a solution to generate a swagger for Giraffe.
My solution for Suave was effectively not really easy to use.
The good news is that we still have to declare our API routes the same way as before but to enable the route analysis we have to surround the app declaration with quotation marks.
With that in place we can decouple the app declaration from the analysis required to generate the swagger documentation. In other words this solution has the avantage to avoid corrupting your service implementation.
How does it work ?
I introduced the
This function does the analysis of your quotation to generate Swagger documentation.
There are 2 solutions to add documentation for a route.
... operationId "send_a_car" ==> consumes tcar ==> produces typeof<Car> ==> route "/car2" >=> submitCar ...
... route "/car" >=> submitCar ... let docAddendums = fun (route:Analyzer.RouteInfos) (path:string,verb:HttpVerb,pathDef:PathDefinition) -> match path,verb,pathDef with | "/car", HttpVerb.Post,def -> let ndef = (def.AddConsume "model" "application/json" Body typeof<Car>) .AddResponse 200 "application/json" "A car" typeof<Car> path, verb, ndef ...
PS: I added a SLN file to improve experience with Jetbrains Rider IDE.
Some features could be missing and some quotations could be difficult to parse.
I only implemented:
@rflechner "I just pushed fixes." - merged your changes to the temporal https://github.com/cotyar/Giraffe/tree/SwaggerAndWebsockets
So, I just tried to get this up and running on my machine (Ubuntu 18.04) and it seemed to work. A few things though:
Hope this helps. Super excited to see this feature get in!!
@rflechner Not able to check at the moment. But while I've got you here, can I suggest making this feature an entirely separate repo/Nuget package? That would allow it to have a separate release cadence from Giraffe and be more flexible about making updates to it.
When I last tested this feature with my project, an exception was thrown at startup (didn't have a chance to look too deeply into it). I'll try to take another look and see what went wrong.