eliascarv / webapi.jl

Make REST APIs quickly and simply.

Welcome everyone, I'm Elias Carvalho!

webapi.jl's Issues

Automatic documentation?

Hey @eliascarv ! What a cool project, I wish this existed 2 years ago!

Did you have any ideas about automatically hosting a documentation page? If you have an endpoint serving the JSON schema of your API, something like https://github.com/swagger-api/swagger-ui can automatically create an interactive docs page for your API!

Here is a python project using this same strategy: https://fastapi.tiangolo.com/#interactive-api-docs

You can use Base.Docs to get docstrings, e.g.:

julia> b = Docs.Binding(Main, :sqrt)
Base.sqrt

julia> docs = Base.Docs.doc(b);

julia> repr(MIME"text/html"(), docs)
"<div class=\"markdown\"><pre><code>sqrt&#40;x&#41;</code></pre>\n<p>Return &#36;\\sqrt&#123;x&#125;&#36;. Throws <a href=\"@ref\"><code>DomainError</code></a> for negative <a href=\"@ref\"><code>Real</code></a> arguments. Use complex negative arguments instead. The prefix opera" ⋯ 2878 bytes ⋯ "95&#40;87&#41;90118-2</a></p>\n</div>\n<h1>Examples</h1>\n<pre><code class=\"language-jldoctest\">julia&gt; A &#61; &#91;4 0; 0 4&#93;\n2×2 Matrix&#123;Int64&#125;:\n 4  0\n 0  4\n\njulia&gt; sqrt&#40;A&#41;\n2×2 Matrix&#123;Float64&#125;:\n 2.0  0.0\n 0.0  2.0</code></pre>\n\n\n</div>"

---

I'm looking forward to see where this package goes! Consider posting a TODO list on your README, or keeping issues with good labels, to let people know how ready-to-use the package is, and in what ways they could contribute!

End-to-end HTTP server tests

You might want to add end-to-end tests where you run the API server with serve(app), and use HTTP.get("http://localhost:2345/hello") to make real requests to your own server. This requires some tricky async code, but this example from Pluto's tests might be helpful:

https://github.com/fonsp/Pluto.jl/blob/ec2bc1cb828d3747700ebd6a50b37ce3980d1a83/test/webserver.jl#L12-L51

Notice that we use polling instead of sleep to deal with the unpredictable nature of running code in the background. The poll function is here, feel free to copy:

https://github.com/fonsp/Pluto.jl/blob/ec2bc1cb828d3747700ebd6a50b37ce3980d1a83/src/evaluation/WorkspaceManager.jl#L481-L524