@@ -20,126 +20,7 @@
2020-- The only thing you'll need to do will be to implement some classes
2121-- for your captures, get parameters and request or response bodies.
2222--
23−-- Here is a complete example that you can run to see the markdown pretty
24−-- printer in action:
25−--
26−-- > {-# LANGUAGE DataKinds #-}
27−-- > {-# LANGUAGE DeriveGeneric #-}
28−-- > {-# LANGUAGE FlexibleInstances #-}
29−-- > {-# LANGUAGE MultiParamTypeClasses #-}
30−-- > {-# LANGUAGE OverloadedStrings #-}
31−-- > {-# LANGUAGE TypeOperators #-}
32−-- > {-# OPTIONS_GHC -fno-warn-orphans #-}
33−-- > import Control.Lens
34−-- > import Data.Aeson
35−-- > import Data.Proxy
36−-- > import Data.String.Conversions
37−-- > import Data.Text (Text)
38−-- > import GHC.Generics
39−-- > import Servant.API
40−-- > import Servant.Docs
41−-- >
42−-- > -- * Example
43−-- >
44−-- > -- | A greet message data type
45−-- > newtype Greet = Greet Text
46−-- > deriving (Generic, Show)
47−-- >
48−-- > -- | We can get JSON support automatically. This will be used to parse
49−-- > -- and encode a Greeting as 'JSON'.
50−-- > instance FromJSON Greet
51−-- > instance ToJSON Greet
52−-- >
53−-- > -- | We can also implement 'MimeRender' for additional formats like 'PlainText'.
54−-- > instance MimeRender PlainText Greet where
55−-- > mimeRender Proxy (Greet s) = "\"" <> cs s <> "\""
56−-- >
57−-- > -- We add some useful annotations to our captures,
58−-- > -- query parameters and request body to make the docs
59−-- > -- really helpful.
60−-- > instance ToCapture (Capture "name" Text) where
61−-- > toCapture _ = DocCapture "name" "name of the person to greet"
62−-- >
63−-- > instance ToCapture (Capture "greetid" Text) where
64−-- > toCapture _ = DocCapture "greetid" "identifier of the greet msg to remove"
65−-- >
66−-- > instance ToParam (QueryParam "capital" Bool) where
67−-- > toParam _ =
68−-- > DocQueryParam "capital"
69−-- > ["true", "false"]
70−-- > "Get the greeting message in uppercase (true) or not (false).\
71−-- > \Default is false."
72−-- > Normal
73−-- >
74−-- > instance ToParam (MatrixParam "lang" String) where
75−-- > toParam _ =
76−-- > DocQueryParam "lang"
77−-- > ["en", "sv", "fr"]
78−-- > "Get the greeting message selected language. Default is en."
79−-- > Normal
80−-- >
81−-- > instance ToSample Greet where
82−-- > toSample _ = Just $ Greet "Hello, haskeller!"
83−-- >
84−-- > toSamples _ =
85−-- > [ ("If you use ?capital=true", Greet "HELLO, HASKELLER")
86−-- > , ("If you use ?capital=false", Greet "Hello, haskeller")
87−-- > ]
88−-- >
89−-- > -- We define some introductory sections, these will appear at the top of the
90−-- > -- documentation.
91−-- > --
92−-- > -- We pass them in with 'docsWith', below. If you only want to add
93−-- > -- introductions, you may use 'docsWithIntros'
94−-- > intro1 :: DocIntro
95−-- > intro1 = DocIntro "On proper introductions." -- The title
96−-- > [ "Hello there."
97−-- > , "As documentation is usually written for humans, it's often useful \
98−-- > \to introduce concepts with a few words." ] -- Elements are paragraphs
99−-- >
100−-- > intro2 :: DocIntro
101−-- > intro2 = DocIntro "This title is below the last"
102−-- > [ "You'll also note that multiple intros are possible." ]
103−-- >
104−-- >
105−-- > -- API specification
106−-- > type TestApi =
107−-- > -- GET /hello/:name?capital={true, false} returns a Greet as JSON or PlainText
108−-- > "hello" :> MatrixParam "lang" String :> Capture "name" Text :> QueryParam "capital" Bool :> Get '[JSON, PlainText] Greet
109−-- >
110−-- > -- POST /greet with a Greet as JSON in the request body,
111−-- > -- returns a Greet as JSON
112−-- > :<|> "greet" :> ReqBody '[JSON] Greet :> Post '[JSON] Greet
113−-- >
114−-- > -- DELETE /greet/:greetid
115−-- > :<|> "greet" :> Capture "greetid" Text :> Delete '[JSON] ()
116−-- >
117−-- > testApi :: Proxy TestApi
118−-- > testApi = Proxy
119−-- >
120−-- > -- Build some extra information for the DELETE /greet/:greetid endpoint. We
121−-- > -- want to add documentation about a secret unicorn header and some extra
122−-- > -- notes.
123−-- > extra :: ExtraInfo TestApi
124−-- > extra =
125−-- > extraInfo (Proxy :: Proxy ("greet" :> Capture "greetid" Text :> Delete '[JSON] ())) $
126−-- > defAction & headers <>~ ["unicorns"]
127−-- > & notes <>~ [ DocNote "Title" ["This is some text"]
128−-- > , DocNote "Second secton" ["And some more"]
129−-- > ]
130−-- >
131−-- > -- Generate the data that lets us have API docs. This
132−-- > -- is derived from the type as well as from
133−-- > -- the 'ToCapture', 'ToParam' and 'ToSample' instances from above.
134−-- > --
135−-- > -- If you didn't want intros and extra information, you could just call:
136−-- > --
137−-- > -- > docs testAPI :: API
138−-- > docsGreet :: API
139−-- > docsGreet = docsWith [intro1, intro2] extra testApi
140−-- >
141−-- > main :: IO ()
142−-- > main = putStrLn $ markdown docsGreet
23+-- See example/greet.hs for an example.
14324module Servant.Docs
14425 ( -- * 'HasDocs' class and key functions
14526 HasDocs(..), docs, markdown