Suave.Swagger

[haf]

https://github.com/SuaveIO/Suave.Swagger

TODO:

• Ensure compiles with Suave master w/ .net core SDK and the full framework
• Ensure FAKE script can build packages for both Suave and Swagger
• Investigate: can the library be used as a shim on top of the Suave functions? Instead of being explicit; can I open a module and have Swagger support?
• See what, if any, overhead it adds to a request
• Ensure library is configurable from the user's perspective without changing the declaration of the API
• PR back improvements, release new beta of Suave and Suave.Swagger.

[tamizhvendan]

Hi @haf,

I can take up the third and fifth item

* Investigate: can the library be used as a shim on top of the Suave functions? Instead of being explicit; can I open a module and have Swagger support?

* Ensure library is configurable from the user's perspective without changing the declaration of the API

Can you provide few more details for these?

[tamizhvendan]

Yesterday I spent some time going through the implementation of @rflechner from his pull request.

The implementation address the fifth item described here (keeping documentation and API as separate). I like his approach on using quotations.

But I am also thinking of something similar to servant library (using Free Monad). I know that the Suave's programming doesn't support it. It'd be great to have the swagger documentation generated automatically (without having a separate manual entry).

[haf]

@tamizhvendan What in the Suave programming model would not support it? Do you mean free monads which is unsupported by F# generally? I do like the way Servant does it, but would angle myself for a more compositional API; the Haskell API composes type classes, which indeed makes for few lines of code, but when you want to vary a specific serialisation function, or a specific documentation function from the norm, you have to add it in a central location. In my own API, I have input builders, that chain serialisers together; I plan on something even more exciting for the next release; but generally, as long as it's composable, we can do anything with it going forward.

[tamizhvendan]

Yes, @haf I meant Free Monad way of interpreting the app declaration and generate documentation out of it like below

let greetings q =
  defaultArg (Option.ofChoice (q ^^ "name")) "World" |> sprintf "Hello %s"

let sample : WebPart = 
    path "/hello" >=> choose [
      GET  >=> request (fun r -> OK (greetings r.query))
      POST >=> request (fun r -> OK (greetings r.form))
      RequestErrors.NOT_FOUND "Found no handlers" ]

let swaggerWebPart = swagger sample

startWebServer defaultConfig swaggerWebPart