servant-docs
generate API docs for your servant webservice
Version on this page: | 0.13@rev:2 |
LTS Haskell 22.33: | 0.13@rev:4 |
Stackage Nightly 2024-09-07: | 0.13.1 |
Latest on Hackage: | 0.13.1 |
servant-docs-0.13@sha256:257c4e1217f97aa0e057bbc3c8b25ff8674dac22cee100fa9738131137a38dab,3413
Module documentation for 0.13
servant-docs
Generate API docs for your servant webservice. Feel free to also take a look at servant-pandoc which uses this package to target a broad range of output formats using the excellent pandoc.
Example
See here for the output of the following program.
{-# LANGUAGE DataKinds #-}
{-# LANGUAGE DeriveGeneric #-}
{-# LANGUAGE FlexibleInstances #-}
{-# LANGUAGE MultiParamTypeClasses #-}
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE PolyKinds #-}
{-# LANGUAGE TypeFamilies #-}
{-# LANGUAGE TypeOperators #-}
import Data.Aeson (FromJSON, ToJSON)
import Data.Proxy (Proxy (..))
import Data.String.Conversions (cs)
import Data.Text (Text)
import GHC.Generics (Generic)
import Servant.API
( (:<|>),
(:>),
Capture,
Delete,
Get,
JSON,
MimeRender,
PlainText,
Post,
QueryParam,
ReqBody,
mimeRender,
)
import Servant.Docs
( API,
DocCapture (..),
DocQueryParam (..),
ParamKind (..),
ToCapture,
ToParam,
ToSample,
docs,
markdown,
singleSample,
toCapture,
toParam,
toSamples,
)
-- our type for a Greeting message
data Greet = Greet { _msg :: Text }
deriving (Generic, Show)
-- we get our JSON serialization for free. This will be used by the default
-- 'MimeRender' instance for 'JSON'.
instance FromJSON Greet
instance ToJSON Greet
instance ToSample ()
-- We can also implement 'MimeRender' explicitly for additional formats.
instance MimeRender PlainText Greet where
mimeRender Proxy (Greet s) = "<h1>" <> cs s <> "</h1>"
-- we provide a sample value for the 'Greet' type
instance ToSample Greet where
toSamples _ = singleSample g
where g = Greet "Hello, haskeller!"
instance ToParam (QueryParam "capital" Bool) where
toParam _ =
DocQueryParam "capital"
["true", "false"]
"Get the greeting message in uppercase (true) or not (false). Default is false."
Normal
instance ToCapture (Capture "name" Text) where
toCapture _ = DocCapture "name" "name of the person to greet"
instance ToCapture (Capture "greetid" Text) where
toCapture _ = DocCapture "greetid" "identifier of the greet msg to remove"
-- API specification
type TestApi =
"hello" :> Capture "name" Text :> QueryParam "capital" Bool :> Get '[JSON,PlainText] Greet
:<|> "greet" :> ReqBody '[JSON] Greet :> Post '[JSON] Greet
:<|> "delete" :> Capture "greetid" Text :> Delete '[JSON] ()
testApi :: Proxy TestApi
testApi = Proxy
-- Generate the Documentation's ADT
greetDocs :: API
greetDocs = docs testApi
main :: IO ()
main = putStrLn $ markdown greetDocs
Changes
The latest version of this document is on GitHub.
Changelog for servant
package contains significant entries for all core packages.
0.13
-
WithResource combinator for Servant-managed resources. #1630
For servant-docs, this meant the addition of
instance HasDocs api => HasDocs (WithResource res :> api)
-
Compatibility with GHC series 9.2, 9.4, 9.6
0.12
Significant changes
- Generate sample cURL requests
(#1401).
Breaking change: requires sample header values to be supplied with
headers
.
0.11.9
Significant changes
- Use Capture Description if available (#1423).
Other changes
- Support GHC-9.0.1.
- Bump
bytestring
andlens
dependencies.
0.11.8
Significant changes
- Support
Fragment
combinator.
0.11.7
Significant changes
- Add instance for ToSample NonEmpty
Other changes
- Bump “tested-with” ghc versions
- Fix servant-docs code sample in README
0.11.5
-
Add NoContentVerb #1028 #1219 #1228
The
NoContent
API endpoints should now useNoContentVerb
combinator. The API type changes are usually of the kind- :<|> PostNoContent '[JSON] NoContent + :<|> PostNoContent
i.e. one doesn’t need to specify the content-type anymore. There is no content.
-
Capture
can beLenient
#1155 #1156You can specify a lenient capture as
:<|> "capture-lenient" :> Capture' '[Lenient] "foo" Int :> GET
which will make the capture always succeed. Handlers will be of the type
Either String CapturedType
, whereLeft err
represents the possible parse failure. -
servant-docs Merge documentation from duplicate routes #1240 #1241
Servant supports defining the same route multiple times with different content-types and result-types, but servant-docs was only documenting the first of copy of such duplicated routes. It now combines the documentation from all the copies.
Unfortunately, it is not yet possible for the documentation to specify multiple status codes.
-
servant-docs Prevent race-conditions in testing #1194
0.11.4
- Drop dependency on
control-monad-omega
in favor ofData.Universe.Helpers
fromuniverse-base
.
0.11.3
- Support
servant-0.15
- Instances for ‘Stream’ and ‘StreamBody’
0.11.2
- Allow
servant-0.13
:- Doesn’t have instances for streaming.
- Servant.API.Modifiers extra information isn’t used.
0.11.1
- Export
DocAuthentication
and related lenses. - Make
defAction
’s documentation visible in Haddock documentation. - Add a markdown header for the Headers an endpoint is sensitive to.
- Document the HTTP Method the parameters of an endpoint belong to
(rather than assuming
GET
for all of them). - Content type of sample response body is also displayed.
- Can now customise various aspects of how the document is produced
using
markdownWith
andRenderingOptions
:- How many content-types for each example are shown
- Whether notes should be grouped together under their own header.
0.11
- changed the type of
rqbody
.
0.10
There are no changes. Released as a part of servant
suite.
0.7.1
- Support GHC 8.0
0.7
- Use
throwError
instead ofthrowE
in documentation
0.5
- Support for the
HttpVersion
,IsSecure
,RemoteHost
andVault
combinators - Support maximum samples setting with new
DocOptions
type (used bydocsWithOptions
anddocsWith
) - Remove redundant second parameter of ToSample
- Add Generic-based default implementation for
ToSample
class - Add more
ToSamples
instances:Bool
,Ordering
, tuples (up to 7),[]
,Maybe
,Either
,Const
,ZipList
and some monoids - Move
toSample
out ofToSample
class - Add a few helper functions to define
toSamples
- Remove matrix params.
- Added support for Basic authentication
0.4
Delete
now is likeGet
,Post
,Put
, andPatch
and returns a response body- Allow for extra information to be added to the docs
- Support content-type aware combinators of servant-0.4
- Render endpoints in a canonical order (https://github.com/haskell-servant/servant-docs/pull/15)
- Remove ToJSON superclass from ToSample
- Split out Internal module
- Add support for response headers
- Allow
ToSample
to return a different type than it’s arguments - Add Proxy argument to
ToSample
0.3
- Add the ability to display multiple responses, with some accompanying
Text
to describe the context in which we get the corresponding JSON. - Expose the
headers
lens - Represent an endpoint’s path as
[String]
(previouslyString
), fixing a corner case where the leading/
would be missing.