Feature/swagger

[rflechner]

Hello,

In this PR I propose a solution to generate a swagger for Giraffe.
Issue #79 has label help wanted 😃 .

My solution for Suave was effectively not really easy to use.
Documentation and service implementation were too strongly coupled and the DSL was really verbose.

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 documents function that takes two arguments:

1. the quotation expression containing webservice implementation.
2. a DocumentationConfig argument.

This function does the analysis of your quotation to generate Swagger documentation.

DocumentationConfig contains the following properties:

• MethodCallRules: allow you to provide custom functions to enrich DSL and / or quotation analysis.
• DocumentationAddendums: allow you to add more informations to the documentation without introducing service implementation modification.

I introduced ==> operator that gives the possibility to add decorations in routes implementations.

Examples

There are 2 solutions to add documentation for a route.

See example

• First one

...
operationId "send_a_car" ==>
	consumes tcar ==>
		produces typeof<Car> ==>
			route "/car2" >=> submitCar
...

• Second one

using DocumentationAddendums

...
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.
I propose to create a separated NuGet for Giraffe.Swagger.
In futur, SwaggerUi could be a submodule of the repository (if you like and accept this PR 😄 ).

Some features could be missing and some quotations could be difficult to parse.
For the moment, analyzer works with most basics default httphandlers.

I only implemented:

• GET
• POST
• PUT
• PATCH
• DELETE
• route
• routeCi
• routef
• setStatusCode
• text
• json
• choose
• subRouteCi
• subRoute

You can build and run SwaggerSample/Program.fs and
go to http://localhost:5000/swaggerui/

Regards.

@rflechner

[cotyar]

@rflechner "I just pushed fixes." - merged your changes to the temporal https://github.com/cotyar/Giraffe/tree/SwaggerAndWebsockets

[zaaack]

Would this support TokenRouter?

[rflechner]

I don't think but I could try to implement this in a next PR or commit.

[NatElkins]

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:

• The version of the dotnet SDK specified in the global.json is not available from the 18.04 repos.
  
  Installing the dotnet-sdk-2.1 package maps to a version number of 2.1.300. So I had to change that in the global.json to get this to build.

• The other thing is that it looks like the dotnet-xunit CLI tool needs to be installed at least once at some point before it can work. I added a line like
  <DotNetCliToolReference Include="dotnet-xunit" Version="2.3.1" /> (based on https://www.nuget.org/packages/dotnet-xunit/) to Giraffe.Tests.fsproj and it started working. Then when I switched back to master and tried to build again, it still worked. So I think resolving the build issue is as simple as adding that line to the tests project.

Hope this helps. Super excited to see this feature get in!!

[NatElkins]

And of course, please let me know if there's anything I can do to help it along @dustinmoris @rflechner

[NatElkins]

I think this is why the tests are failing.

[ElijahReva]

@rflechner Could you give me access to this branch so I could fix it?

[ElijahReva]

@rflechner Thank you!

[rflechner]

@ElijahReva @NatElkins, is it right for you now ?

[NatElkins]

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

[NatElkins]

Also then @dustinmoris won't have to worry about it affecting the larger Giraffe code base.

[rflechner]

This PR is a technical proposition.
I think we should create another repository / nuget (in alpha) to be more agile.
Do you want to create a repo in your organization (https://github.com/giraffe-fsharp) ?

[cotyar]

Guys, @dustinmoris hasn't updated Giraffe since Feb.
Does anyone know if he's alright and if he still would like to continue supporting the project please?

[NatElkins]

@cotyar The develop branch was updated in May.

[czifro]

What's the best way to try this out while this PR is pending?

[rflechner]

I am closing this PR.
You can try the solution here: https://github.com/rflechner/SwaggerForFsharp

[dustinmoris]

#310