@@ -1,3 +1,10 @@
1+-- | This module defines sever-side handlers that let you serve static files
2+-- and your API's docs.
4+-- - 'serveDirectory' lets you serve anything that lives under a particular
5+-- directory on your filesystem.
6+-- - 'serveDocumentation' lets you serve the markdown-version of the docs for
1module Servant.Utils.StaticFiles (
8module Servant.Utils.StaticFiles (
2 serveDirectory,
9 serveDirectory,
3 serveDocumentation,
10 serveDocumentation,
@@ -14,10 +21,41 @@ import Servant.API.Raw
14import Servant.Docs
21import Servant.Docs
15import Servant.Server
22import Servant.Server
24+-- | Serve anything under the specified directory as a 'Raw' endpoint.
27+-- type MyApi = "static" :> Raw
29+-- server :: Server MyApi
30+-- server = serveDirectory "\/var\/www"
33+-- would capture any request to @\/static\/\<something>@ and look for
34+-- @\<something>@ under @\/var\/www@.
36+-- It will do its best to guess the MIME type for that file, based on the extension,
37+-- and send an appropriate /Content-Type/ header if possible.
39+-- If your goal is to serve HTML, CSS and Javascript files that use the rest of the API
40+-- as a webapp backend, you will most likely not want the static files to be hidden
41+-- behind a /\/static\// prefix. In that case, remember to put the 'serveDirectory'
42+-- handler in the last position, because /servant/ will try to match the handlers
17serveDirectory :: FilePath -> Server Raw
44serveDirectory :: FilePath -> Server Raw
18serveDirectory documentRoot =
45serveDirectory documentRoot =
19 staticApp (defaultFileServerSettings (decodeString (documentRoot ++ "/")))
46 staticApp (defaultFileServerSettings (decodeString (documentRoot ++ "/")))
48+-- | Serve your API's docs as markdown embedded in an html \<pre> tag.
50+-- > type MyApi = "users" :> Get [User]
51+-- > :<|> "docs :> Raw
53+-- > apiProxy :: Proxy MyApi
56+-- > server :: Server MyApi
57+-- > server = listUsers
58+-- > :<|> serveDocumentation apiProxy
21serveDocumentation :: HasDocs api => Proxy api -> Server Raw
59serveDocumentation :: HasDocs api => Proxy api -> Server Raw
22serveDocumentation proxy _request respond =
60serveDocumentation proxy _request respond =
23 respond $ responseLBS ok200 [] $ cs $ toHtml $ markdown $ docs proxy
61 respond $ responseLBS ok200 [] $ cs $ toHtml $ markdown $ docs proxy