Haddocks for the StaticFiles module

This commit is contained in:
Alp Mestanogullari 2014-11-25 15:48:30 +01:00
parent 5b5f530406
commit 5435dd4032

View file

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