git.iko.soy/typeable/servant
on 3bcbe80 help sign in
typeable/servant/servant-docs/example/greet.hs
123 lines 4.2 kB history raw
1{-# LANGUAGE DataKinds #-}
2{-# LANGUAGE DeriveGeneric #-}
3{-# LANGUAGE FlexibleInstances #-}
4{-# LANGUAGE MultiParamTypeClasses #-}
5{-# LANGUAGE OverloadedStrings #-}
6{-# LANGUAGE TypeOperators #-}
7{-# OPTIONS_GHC -fno-warn-orphans #-}
8import Control.Lens
9import Data.Aeson
10import Data.Proxy
11import Data.String.Conversions
12import Data.Text (Text)
13import GHC.Generics
14import Servant.API
15import Servant.Docs
17-- * Example
19-- | A greet message data type
20newtype Greet = Greet Text
21 deriving (Generic, Show)
23-- | We can get JSON support automatically. This will be used to parse
24-- and encode a Greeting as 'JSON'.
25instance FromJSON Greet
26instance ToJSON Greet
28-- | We can also implement 'MimeRender' for additional formats like 'PlainText'.
29instance MimeRender PlainText Greet where
30 mimeRender Proxy (Greet s) = "\"" <> cs s <> "\""
32-- We add some useful annotations to our captures,
33-- query parameters and request body to make the docs
34-- really helpful.
35instance ToCapture (Capture "name" Text) where
36 toCapture _ = DocCapture "name" "name of the person to greet"
38instance ToCapture (Capture "greetid" Text) where
39 toCapture _ = DocCapture "greetid" "identifier of the greet msg to remove"
41instance ToParam (QueryParam "capital" Bool) where
42 toParam _ =
43 DocQueryParam "capital"
44 ["true", "false"]
45 "Get the greeting message in uppercase (true) or not (false).\
46 \Default is false."
47 Normal
49instance ToParam (MatrixParam "lang" String) where
50 toParam _ =
51 DocQueryParam "lang"
52 ["en", "sv", "fr"]
53 "Get the greeting message selected language. Default is en."
54 Normal
56instance ToSample () () where
57 toSample _ = Just ()
59instance ToSample Greet Greet where
60 toSample _ = Just $ Greet "Hello, haskeller!"
62 toSamples _ =
63 [ ("If you use ?capital=true", Greet "HELLO, HASKELLER")
64 , ("If you use ?capital=false", Greet "Hello, haskeller")
65 ]
67instance ToSample Int Int where
68 toSample _ = Just 1729
70-- We define some introductory sections, these will appear at the top of the
71-- documentation.
72--
73-- We pass them in with 'docsWith', below. If you only want to add
74-- introductions, you may use 'docsWithIntros'
75intro1 :: DocIntro
76intro1 = DocIntro "On proper introductions." -- The title
77 [ "Hello there."
78 , "As documentation is usually written for humans, it's often useful \
79 \to introduce concepts with a few words." ] -- Elements are paragraphs
81intro2 :: DocIntro
82intro2 = DocIntro "This title is below the last"
83 [ "You'll also note that multiple intros are possible." ]
86-- API specification
87type TestApi =
88 -- GET /hello/:name?capital={true, false} returns a Greet as JSON or PlainText
89 "hello" :> MatrixParam "lang" String :> Capture "name" Text :> QueryParam "capital" Bool :> Get '[JSON, PlainText] Greet
91 -- POST /greet with a Greet as JSON in the request body,
92 -- returns a Greet as JSON
93 :<|> "greet" :> ReqBody '[JSON] Greet :> Post '[JSON] (Headers '[Header "X-Example" Int] Greet)
95 -- DELETE /greet/:greetid
96 :<|> "greet" :> Capture "greetid" Text :> Delete '[JSON] ()
98testApi :: Proxy TestApi
99testApi = Proxy
101-- Build some extra information for the DELETE /greet/:greetid endpoint. We
102-- want to add documentation about a secret unicorn header and some extra
103-- notes.
104extra :: ExtraInfo TestApi
105extra =
106 extraInfo (Proxy :: Proxy ("greet" :> Capture "greetid" Text :> Delete '[JSON] ())) $
107 defAction & headers <>~ ["unicorns"]
108 & notes <>~ [ DocNote "Title" ["This is some text"]
109 , DocNote "Second secton" ["And some more"]
110 ]
112-- Generate the data that lets us have API docs. This
113-- is derived from the type as well as from
114-- the 'ToCapture', 'ToParam' and 'ToSample' instances from above.
115--
116-- If you didn't want intros and extra information, you could just call:
117--
118-- > docs testAPI :: API
119docsGreet :: API
120docsGreet = docsWith [intro1, intro2] extra testApi
122main :: IO ()
123main = putStrLn $ markdown docsGreet