-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | generate API docs for your servant webservice
--   
@package servant-docs
@version 0.4.2

module Servant.Docs.Internal

-- | Supported HTTP request methods
data Method

-- | the DELETE method
DocDELETE :: Method

-- | the GET method
DocGET :: Method

-- | the POST method
DocPOST :: Method

-- | the PUT method
DocPUT :: Method

-- | An <a>Endpoint</a> type that holds the <a>path</a> and the
--   <a>method</a>.
--   
--   Gets used as the key in the <a>API</a> hashmap. Modify
--   <a>defEndpoint</a> or any <a>Endpoint</a> value you want using the
--   <a>path</a> and <a>method</a> lenses to tweak.
--   
--   <pre>
--   λ&gt; <a>defEndpoint</a>
--   GET /
--   λ&gt; <a>defEndpoint</a> &amp; <a>path</a> <a>&lt;&gt;~</a> ["foo"]
--   GET /foo
--   λ&gt; <a>defEndpoint</a> &amp; <a>path</a> <a>&lt;&gt;~</a> ["foo"] &amp; <a>method</a> <a>.~</a> <a>DocPOST</a>
--   POST /foo
--   </pre>
data Endpoint
Endpoint :: [String] -> Method -> Endpoint
_path :: Endpoint -> [String]
_method :: Endpoint -> Method

-- | Render a path as a <a>/</a>-delimited string
showPath :: [String] -> String

-- | An <a>Endpoint</a> whose path is `"/"` and whose method is
--   <a>DocGET</a>
--   
--   Here's how you can modify it:
--   
--   <pre>
--   λ&gt; <a>defEndpoint</a>
--   GET /
--   λ&gt; <a>defEndpoint</a> &amp; <a>path</a> <a>&lt;&gt;~</a> ["foo"]
--   GET /foo
--   λ&gt; <a>defEndpoint</a> &amp; <a>path</a> <a>&lt;&gt;~</a> ["foo"] &amp; <a>method</a> <a>.~</a> <a>DocPOST</a>
--   POST /foo
--   </pre>
defEndpoint :: Endpoint

-- | Our API documentation type, a product of top-level information and a
--   good old hashmap from <a>Endpoint</a> to <a>Action</a>
data API
API :: [DocIntro] -> HashMap Endpoint Action -> API
_apiIntros :: API -> [DocIntro]
_apiEndpoints :: API -> HashMap Endpoint Action

-- | An empty <a>API</a>
emptyAPI :: API

-- | A type to represent captures. Holds the name of the capture and a
--   description.
--   
--   Write a <a>ToCapture</a> instance for your captured types.
data DocCapture
DocCapture :: String -> String -> DocCapture
_capSymbol :: DocCapture -> String
_capDesc :: DocCapture -> String

-- | A type to represent a <i>GET</i> parameter from the Query String.
--   Holds its name, the possible values (leave empty if there isn't a
--   finite number of them), and a description of how it influences the
--   output or behavior.
--   
--   Write a <a>ToParam</a> instance for your GET parameter types
data DocQueryParam
DocQueryParam :: String -> [String] -> String -> ParamKind -> DocQueryParam
_paramName :: DocQueryParam -> String
_paramValues :: DocQueryParam -> [String]
_paramDesc :: DocQueryParam -> String
_paramKind :: DocQueryParam -> ParamKind

-- | An introductory paragraph for your documentation. You can pass these
--   to <a>docsWithIntros</a>.
data DocIntro
DocIntro :: String -> [String] -> DocIntro

-- | Appears above the intro blob
_introTitle :: DocIntro -> String

-- | Each String is a paragraph.
_introBody :: DocIntro -> [String]

-- | A type to represent extra notes that may be attached to an
--   <a>Action</a>.
--   
--   This is intended to be used when writing your own HasDocs instances to
--   add extra sections to your endpoint's documentation.
data DocNote
DocNote :: String -> [String] -> DocNote
_noteTitle :: DocNote -> String
_noteBody :: DocNote -> [String]

-- | Type of extra information that a user may wish to "union" with their
--   documentation.
--   
--   These are intended to be built using extraInfo. Multiple ExtraInfo may
--   be combined with the monoid instance.
newtype ExtraInfo layout
ExtraInfo :: (HashMap Endpoint Action) -> ExtraInfo layout

-- | Type of GET parameter:
--   
--   <ul>
--   <li>Normal corresponds to <tt>QueryParam</tt>, i.e your usual GET
--   parameter</li>
--   <li>List corresponds to <tt>QueryParams</tt>, i.e GET parameters with
--   multiple values</li>
--   <li>Flag corresponds to <tt>QueryFlag</tt>, i.e a value-less GET
--   parameter</li>
--   </ul>
data ParamKind
Normal :: ParamKind
List :: ParamKind
Flag :: ParamKind

-- | A type to represent an HTTP response. Has an <a>Int</a> status, a list
--   of possible <tt>MediaType</tt>s, and a list of example
--   <a>ByteString</a> response bodies. Tweak <a>defResponse</a> using the
--   <a>respStatus</a>, <a>respTypes</a> and <a>respBody</a> lenses if you
--   want.
--   
--   If you want to respond with a non-empty response body, you'll most
--   likely want to write a <a>ToSample</a> instance for the type that'll
--   be represented as encoded data in the response.
--   
--   Can be tweaked with three lenses.
--   
--   <pre>
--   λ&gt; defResponse
--   Response {_respStatus = 200, _respTypes = [], _respBody = []}
--   λ&gt; defResponse &amp; respStatus .~ 204 &amp; respBody .~ [("If everything goes well", "{ \"status\": \"ok\" }")]
--   Response {_respStatus = 204, _respTypes = [], _respBody = [("If everything goes well", "{ \"status\": \"ok\" }")]}
--   </pre>
data Response
Response :: Int -> [MediaType] -> [(Text, MediaType, ByteString)] -> [Header] -> Response
_respStatus :: Response -> Int
_respTypes :: Response -> [MediaType]
_respBody :: Response -> [(Text, MediaType, ByteString)]
_respHeaders :: Response -> [Header]

-- | Default response: status code 200, no response body.
--   
--   Can be tweaked with two lenses.
--   
--   <pre>
--   λ&gt; defResponse
--   Response {_respStatus = 200, _respBody = Nothing}
--   λ&gt; defResponse &amp; respStatus .~ 204 &amp; respBody .~ Just "[]"
--   Response {_respStatus = 204, _respBody = Just "[]"}
--   </pre>
defResponse :: Response

-- | A datatype that represents everything that can happen at an endpoint,
--   with its lenses:
--   
--   <ul>
--   <li>List of captures (<a>captures</a>)</li>
--   <li>List of GET parameters (<a>params</a>)</li>
--   <li>What the request body should look like, if any is requested
--   (<a>rqbody</a>)</li>
--   <li>What the response should be if everything goes well
--   (<a>response</a>)</li>
--   </ul>
--   
--   You can tweak an <a>Action</a> (like the default <a>defAction</a>)
--   with these lenses to transform an action and add some information to
--   it.
data Action
Action :: [DocCapture] -> [Text] -> [DocQueryParam] -> [DocNote] -> [(String, [DocQueryParam])] -> [MediaType] -> [(MediaType, ByteString)] -> Response -> Action
_captures :: Action -> [DocCapture]
_headers :: Action -> [Text]
_params :: Action -> [DocQueryParam]
_notes :: Action -> [DocNote]
_mxParams :: Action -> [(String, [DocQueryParam])]
_rqtypes :: Action -> [MediaType]
_rqbody :: Action -> [(MediaType, ByteString)]
_response :: Action -> Response

-- | Combine two Actions, we can't make a monoid as merging Response breaks
--   the laws.
--   
--   As such, we invent a non-commutative, left associative operation
--   <a>combineAction</a> to mush two together taking the response, body
--   and content types from the very left.
combineAction :: Action -> Action -> Action
defAction :: Action

-- | Create an API that's comprised of a single endpoint. <a>API</a> is a
--   <a>Monoid</a>, so combine multiple endpoints with <a>mappend</a> or
--   <a>&lt;&gt;</a>.
single :: Endpoint -> Action -> API
apiIntros :: Lens' API [DocIntro]
apiEndpoints :: Lens' API (HashMap Endpoint Action)
path :: Lens' Endpoint [String]
method :: Lens' Endpoint Method
capSymbol :: Lens' DocCapture String
capDesc :: Lens' DocCapture String
paramValues :: Lens' DocQueryParam [String]
paramName :: Lens' DocQueryParam String
paramKind :: Lens' DocQueryParam ParamKind
paramDesc :: Lens' DocQueryParam String
introTitle :: Lens' DocIntro String
introBody :: Lens' DocIntro [String]
noteTitle :: Lens' DocNote String
noteBody :: Lens' DocNote [String]
respTypes :: Lens' Response [MediaType]
respStatus :: Lens' Response Int
respHeaders :: Lens' Response [Header]
respBody :: Lens' Response [(Text, MediaType, ByteString)]
rqtypes :: Lens' Action [MediaType]
rqbody :: Lens' Action [(MediaType, ByteString)]
response :: Lens' Action Response
params :: Lens' Action [DocQueryParam]
notes :: Lens' Action [DocNote]
mxParams :: Lens' Action [(String, [DocQueryParam])]
headers :: Lens' Action [Text]
captures :: Lens' Action [DocCapture]

-- | Generate the docs for a given API that implements <a>HasDocs</a>. This
--   is the default way to create documentation.
docs :: HasDocs layout => Proxy layout -> API

-- | Closed type family, check if endpoint is exactly within API.

-- | Create an <a>ExtraInfo</a> that is garunteed to be within the given
--   API layout.
--   
--   The safety here is to ensure that you only add custom documentation to
--   an endpoint that actually exists within your API.
--   
--   <pre>
--   extra :: ExtraInfo TestApi
--   extra =
--       extraInfo (Proxy :: Proxy ("greet" :&gt; Capture "greetid" Text :&gt; Delete)) $
--                defAction &amp; headers &lt;&gt;~ ["unicorns"]
--                          &amp; notes   &lt;&gt;~ [ DocNote "Title" ["This is some text"]
--                                        , DocNote "Second secton" ["And some more"]
--                                        ]
--   </pre>
extraInfo :: (IsIn endpoint layout, HasLink endpoint, HasDocs endpoint) => Proxy endpoint -> Action -> ExtraInfo layout

-- | Generate documentation given some extra introductions (in the form of
--   <tt>DocInfo</tt>) and some extra endpoint documentation (in the form
--   of <a>ExtraInfo</a>.
--   
--   The extra introductions will be prepended to the top of the
--   documentation, before the specific endpoint documentation. The extra
--   endpoint documentation will be "unioned" with the automatically
--   generated endpoint documentation.
--   
--   You are expected to build up the ExtraInfo with the Monoid instance
--   and <a>extraInfo</a>.
--   
--   If you only want to add an introduction, use <a>docsWithIntros</a>.
docsWith :: HasDocs layout => [DocIntro] -> ExtraInfo layout -> Proxy layout -> API

-- | Generate the docs for a given API that implements <a>HasDocs</a> with
--   with any number of introduction(s)
docsWithIntros :: HasDocs layout => [DocIntro] -> Proxy layout -> API

-- | The class that abstracts away the impact of API combinators on
--   documentation generation.
class HasDocs layout
docsFor :: HasDocs layout => Proxy layout -> (Endpoint, Action) -> API

-- | The class that lets us display a sample input or output in the
--   supported content-types when generating documentation for endpoints
--   that either:
--   
--   <ul>
--   <li>expect a request body, or</li>
--   <li>return a non empty response body</li>
--   </ul>
--   
--   Example of an instance:
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric #-}
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   import Data.Aeson
--   import Data.Text
--   import GHC.Generics
--   
--   data Greet = Greet { _msg :: Text }
--     deriving (Generic, Show)
--   
--   instance FromJSON Greet
--   instance ToJSON Greet
--   
--   instance ToSample Greet Greet where
--     toSample _ = Just g
--   
--       where g = Greet "Hello, haskeller!"
--   </pre>
--   
--   You can also instantiate this class using <a>toSamples</a> instead of
--   <a>toSample</a>: it lets you specify different responses along with
--   some context (as <a>Text</a>) that explains when you're supposed to
--   get the corresponding response.
class ToSample a b | a -> b where toSample _ = snd <$> listToMaybe samples where samples = toSamples (Proxy :: Proxy a) toSamples _ = maybe [] (return . ("",)) s where s = toSample (Proxy :: Proxy a)
toSample :: ToSample a b => Proxy a -> Maybe b
toSamples :: ToSample a b => Proxy a -> [(Text, b)]
class AllHeaderSamples ls
allHeaderToSample :: AllHeaderSamples ls => Proxy ls -> [Header]

-- | Synthesise a sample value of a type, encoded in the specified media
--   types.
sampleByteString :: (ToSample a b, IsNonEmpty ctypes, AllMimeRender ctypes b) => Proxy ctypes -> Proxy a -> [(MediaType, ByteString)]

-- | Synthesise a list of sample values of a particular type, encoded in
--   the specified media types.
sampleByteStrings :: (ToSample a b, IsNonEmpty ctypes, AllMimeRender ctypes b) => Proxy ctypes -> Proxy a -> [(Text, MediaType, ByteString)]

-- | Generate a list of <tt>MediaType</tt> values describing the content
--   types accepted by an API component.
class SupportedTypes (list :: [*])
supportedTypes :: SupportedTypes list => Proxy list -> [MediaType]

-- | The class that helps us automatically get documentation for GET
--   parameters.
--   
--   Example of an instance:
--   
--   <pre>
--   instance ToParam (QueryParam "capital" Bool) where
--     toParam _ =
--       DocQueryParam "capital"
--                     ["true", "false"]
--                     "Get the greeting message in uppercase (true) or not (false). Default is false."
--   </pre>
class ToParam t
toParam :: ToParam t => Proxy t -> DocQueryParam

-- | The class that helps us automatically get documentation for URL
--   captures.
--   
--   Example of an instance:
--   
--   <pre>
--   instance ToCapture (Capture "name" Text) where
--     toCapture _ = DocCapture "name" "name of the person to greet"
--   </pre>
class ToCapture c
toCapture :: ToCapture c => Proxy c -> DocCapture

-- | Generate documentation in Markdown format for the given <a>API</a>.
markdown :: API -> String

-- | The generated docs for <tt>a <a>:&lt;|&gt;</a> b</tt> just appends the
--   docs for <tt>a</tt> with the docs for <tt>b</tt>.

-- | <tt>"books" :&gt; <a>Capture</a> "isbn" Text</tt> will appear as
--   <tt><i>books</i>:isbn</tt> in the docs.
instance [overlap ok] (KnownSymbol path, HasDocs sublayout) => HasDocs (path :> sublayout)
instance [overlap ok] (ToSample a b, IsNonEmpty cts, AllMimeRender cts b, HasDocs sublayout, SupportedTypes cts) => HasDocs (ReqBody cts a :> sublayout)
instance [overlap ok] HasDocs Raw
instance [overlap ok] (KnownSymbol sym, HasDocs sublayout) => HasDocs (MatrixFlag sym :> sublayout)
instance [overlap ok] (KnownSymbol sym, HasDocs sublayout) => HasDocs (MatrixParams sym a :> sublayout)
instance [overlap ok] (KnownSymbol sym, ToParam (MatrixParam sym a), HasDocs sublayout) => HasDocs (MatrixParam sym a :> sublayout)
instance [overlap ok] (KnownSymbol sym, ToParam (QueryFlag sym), HasDocs sublayout) => HasDocs (QueryFlag sym :> sublayout)
instance [overlap ok] (KnownSymbol sym, ToParam (QueryParams sym a), HasDocs sublayout) => HasDocs (QueryParams sym a :> sublayout)
instance [overlap ok] (KnownSymbol sym, ToParam (QueryParam sym a), HasDocs sublayout) => HasDocs (QueryParam sym a :> sublayout)
instance [overlap ok] (ToSample a b, IsNonEmpty cts, AllMimeRender cts b, SupportedTypes cts, AllHeaderSamples ls, GetHeaders (HList ls)) => HasDocs (Put cts (Headers ls a))
instance [overlap ok] (ToSample a b, IsNonEmpty cts, AllMimeRender cts b, SupportedTypes cts) => HasDocs (Put cts a)
instance [overlap ok] (ToSample a b, IsNonEmpty cts, AllMimeRender cts b, SupportedTypes cts, AllHeaderSamples ls, GetHeaders (HList ls)) => HasDocs (Post cts (Headers ls a))
instance [overlap ok] (ToSample a b, IsNonEmpty cts, AllMimeRender cts b, SupportedTypes cts) => HasDocs (Post cts a)
instance [overlap ok] (KnownSymbol sym, HasDocs sublayout) => HasDocs (Header sym a :> sublayout)
instance [overlap ok] (ToSample a b, IsNonEmpty cts, AllMimeRender cts b, SupportedTypes cts, AllHeaderSamples ls, GetHeaders (HList ls)) => HasDocs (Get cts (Headers ls a))
instance [overlap ok] (ToSample a b, IsNonEmpty cts, AllMimeRender cts b, SupportedTypes cts) => HasDocs (Get cts a)
instance [overlap ok] (ToSample a b, IsNonEmpty cts, AllMimeRender cts b, SupportedTypes cts, AllHeaderSamples ls, GetHeaders (HList ls)) => HasDocs (Delete cts (Headers ls a))
instance [overlap ok] (ToSample a b, IsNonEmpty cts, AllMimeRender cts b, SupportedTypes cts) => HasDocs (Delete cts a)
instance [overlap ok] (KnownSymbol sym, ToCapture (Capture sym a), HasDocs sublayout) => HasDocs (Capture sym a :> sublayout)
instance [overlap ok] (HasDocs layout1, HasDocs layout2) => HasDocs (layout1 :<|> layout2)
instance [overlap ok] (Accept ctype, SupportedTypes rest) => SupportedTypes (ctype : rest)
instance [overlap ok] SupportedTypes '[]
instance [overlap ok] (ToByteString l, AllHeaderSamples ls, ToSample l l, KnownSymbol h) => AllHeaderSamples (Header h l : ls)
instance [overlap ok] AllHeaderSamples '[]
instance [overlap ok] ToSample a b => ToSample (Headers ls a) b
instance [overlap ok] Eq Method
instance [overlap ok] Ord Method
instance [overlap ok] Generic Method
instance [overlap ok] Eq Endpoint
instance [overlap ok] Ord Endpoint
instance [overlap ok] Generic Endpoint
instance [overlap ok] Eq DocCapture
instance [overlap ok] Ord DocCapture
instance [overlap ok] Show DocCapture
instance [overlap ok] Eq DocIntro
instance [overlap ok] Show DocIntro
instance [overlap ok] Eq DocNote
instance [overlap ok] Ord DocNote
instance [overlap ok] Show DocNote
instance [overlap ok] Eq ParamKind
instance [overlap ok] Ord ParamKind
instance [overlap ok] Show ParamKind
instance [overlap ok] Eq DocQueryParam
instance [overlap ok] Ord DocQueryParam
instance [overlap ok] Show DocQueryParam
instance [overlap ok] Eq Response
instance [overlap ok] Ord Response
instance [overlap ok] Show Response
instance [overlap ok] Eq Action
instance [overlap ok] Ord Action
instance [overlap ok] Show Action
instance [overlap ok] Eq API
instance [overlap ok] Show API
instance Datatype D1Method
instance Constructor C1_0Method
instance Constructor C1_1Method
instance Constructor C1_2Method
instance Constructor C1_3Method
instance Datatype D1Endpoint
instance Constructor C1_0Endpoint
instance Selector S1_0_0Endpoint
instance Selector S1_0_1Endpoint
instance [overlap ok] Monoid (ExtraInfo a)
instance [overlap ok] Ord DocIntro
instance [overlap ok] Monoid API
instance [overlap ok] Hashable Endpoint
instance [overlap ok] Show Endpoint
instance [overlap ok] Hashable Method
instance [overlap ok] Show Method


-- | This module lets you get API docs for free. It lets you generate an
--   <a>API</a> from the type that represents your API using <a>docs</a>:
--   
--   <pre>
--   docs :: <a>HasDocs</a> api =&gt; <tt>Proxy</tt> api -&gt; <a>API</a>
--   </pre>
--   
--   Alternatively, if you wish to add one or more introductions to your
--   documentation, use <a>docsWithIntros</a>:
--   
--   <pre>
--   <a>docsWithIntros</a> :: <a>HasDocs</a> api =&gt; [DocIntro] -&gt; <tt>Proxy</tt> api -&gt; <a>API</a>
--   </pre>
--   
--   You can then call <a>markdown</a> on the <a>API</a> value:
--   
--   <pre>
--   <a>markdown</a> :: <a>API</a> -&gt; String
--   </pre>
--   
--   or define a custom pretty printer:
--   
--   <pre>
--   yourPrettyDocs :: <a>API</a> -&gt; String -- or blaze-html's HTML, or ...
--   </pre>
--   
--   The only thing you'll need to do will be to implement some classes for
--   your captures, get parameters and request or response bodies.
--   
--   Here is a complete example that you can run to see the markdown pretty
--   printer in action:
--   
--   <pre>
--   {-# LANGUAGE DataKinds             #-}
--   {-# LANGUAGE DeriveGeneric         #-}
--   {-# LANGUAGE FlexibleInstances     #-}
--   {-# LANGUAGE MultiParamTypeClasses #-}
--   {-# LANGUAGE OverloadedStrings     #-}
--   {-# LANGUAGE TypeOperators         #-}
--   {-# OPTIONS_GHC -fno-warn-orphans #-}
--   import Control.Lens
--   import Data.Aeson
--   import Data.Proxy
--   import Data.String.Conversions
--   import Data.Text (Text)
--   import GHC.Generics
--   import Servant.API
--   import Servant.Docs
--   
--   -- * Example
--   
--   -- | A greet message data type
--   newtype Greet = Greet Text
--     deriving (Generic, Show)
--   
--   -- | We can get JSON support automatically. This will be used to parse
--   -- and encode a Greeting as 'JSON'.
--   instance FromJSON Greet
--   instance ToJSON Greet
--   
--   -- | We can also implement 'MimeRender' for additional formats like 'PlainText'.
--   instance MimeRender PlainText Greet where
--       mimeRender Proxy (Greet s) = "\"" &lt;&gt; cs s &lt;&gt; "\""
--   
--   -- We add some useful annotations to our captures,
--   -- query parameters and request body to make the docs
--   -- really helpful.
--   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"
--   
--   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 ToParam (MatrixParam "lang" String) where
--     toParam _ =
--       DocQueryParam "lang"
--                     ["en", "sv", "fr"]
--                     "Get the greeting message selected language. Default is en."
--                     Normal
--   
--   instance ToSample Greet Greet where
--     toSample _ = Just $ Greet "Hello, haskeller!"
--   
--     toSamples _ =
--       [ ("If you use ?capital=true", Greet "HELLO, HASKELLER")
--       , ("If you use ?capital=false", Greet "Hello, haskeller")
--       ]
--   
--   -- We define some introductory sections, these will appear at the top of the
--   -- documentation.
--   --
--   -- We pass them in with 'docsWith', below. If you only want to add
--   -- introductions, you may use 'docsWithIntros'
--   intro1 :: DocIntro
--   intro1 = DocIntro "On proper introductions." -- The title
--       [ "Hello there."
--       , "As documentation is usually written for humans, it's often useful \
--         \to introduce concepts with a few words." ] -- Elements are paragraphs
--   
--   intro2 :: DocIntro
--   intro2 = DocIntro "This title is below the last"
--       [ "You'll also note that multiple intros are possible." ]
--   
--   
--   -- API specification
--   type TestApi =
--          -- GET /hello/:name?capital={true, false}  returns a Greet as JSON or PlainText
--          "hello" :&gt; MatrixParam "lang" String :&gt; Capture "name" Text :&gt; QueryParam "capital" Bool :&gt; Get '[JSON, PlainText] Greet
--   
--          -- POST /greet with a Greet as JSON in the request body,
--          --             returns a Greet as JSON
--     :&lt;|&gt; "greet" :&gt; ReqBody '[JSON] Greet :&gt; Post '[JSON] Greet
--   
--          -- DELETE /greet/:greetid
--     :&lt;|&gt; "greet" :&gt; Capture "greetid" Text :&gt; Delete '[JSON] ()
--   
--   testApi :: Proxy TestApi
--   testApi = Proxy
--   
--   -- Build some extra information for the DELETE /greet/:greetid endpoint. We
--   -- want to add documentation about a secret unicorn header and some extra
--   -- notes.
--   extra :: ExtraInfo TestApi
--   extra =
--       extraInfo (Proxy :: Proxy ("greet" :&gt; Capture "greetid" Text :&gt; Delete '[JSON] ())) $
--                defAction &amp; headers &lt;&gt;~ ["unicorns"]
--                          &amp; notes   &lt;&gt;~ [ DocNote "Title" ["This is some text"]
--                                        , DocNote "Second secton" ["And some more"]
--                                        ]
--   
--   -- Generate the data that lets us have API docs. This
--   -- is derived from the type as well as from
--   -- the 'ToCapture', 'ToParam' and 'ToSample' instances from above.
--   --
--   -- If you didn't want intros and extra information, you could just call:
--   --
--   -- &gt; docs testAPI :: API
--   docsGreet :: API
--   docsGreet = docsWith [intro1, intro2] extra testApi
--   
--   main :: IO ()
--   main = putStrLn $ markdown docsGreet
--   </pre>
module Servant.Docs

-- | The class that abstracts away the impact of API combinators on
--   documentation generation.
class HasDocs layout
docsFor :: HasDocs layout => Proxy layout -> (Endpoint, Action) -> API

-- | Generate the docs for a given API that implements <a>HasDocs</a>. This
--   is the default way to create documentation.
docs :: HasDocs layout => Proxy layout -> API

-- | Generate documentation in Markdown format for the given <a>API</a>.
markdown :: API -> String

-- | Type of extra information that a user may wish to "union" with their
--   documentation.
--   
--   These are intended to be built using extraInfo. Multiple ExtraInfo may
--   be combined with the monoid instance.
newtype ExtraInfo layout
ExtraInfo :: (HashMap Endpoint Action) -> ExtraInfo layout

-- | Generate documentation given some extra introductions (in the form of
--   <tt>DocInfo</tt>) and some extra endpoint documentation (in the form
--   of <a>ExtraInfo</a>.
--   
--   The extra introductions will be prepended to the top of the
--   documentation, before the specific endpoint documentation. The extra
--   endpoint documentation will be "unioned" with the automatically
--   generated endpoint documentation.
--   
--   You are expected to build up the ExtraInfo with the Monoid instance
--   and <a>extraInfo</a>.
--   
--   If you only want to add an introduction, use <a>docsWithIntros</a>.
docsWith :: HasDocs layout => [DocIntro] -> ExtraInfo layout -> Proxy layout -> API

-- | Generate the docs for a given API that implements <a>HasDocs</a> with
--   with any number of introduction(s)
docsWithIntros :: HasDocs layout => [DocIntro] -> Proxy layout -> API

-- | Create an <a>ExtraInfo</a> that is garunteed to be within the given
--   API layout.
--   
--   The safety here is to ensure that you only add custom documentation to
--   an endpoint that actually exists within your API.
--   
--   <pre>
--   extra :: ExtraInfo TestApi
--   extra =
--       extraInfo (Proxy :: Proxy ("greet" :&gt; Capture "greetid" Text :&gt; Delete)) $
--                defAction &amp; headers &lt;&gt;~ ["unicorns"]
--                          &amp; notes   &lt;&gt;~ [ DocNote "Title" ["This is some text"]
--                                        , DocNote "Second secton" ["And some more"]
--                                        ]
--   </pre>
extraInfo :: (IsIn endpoint layout, HasLink endpoint, HasDocs endpoint) => Proxy endpoint -> Action -> ExtraInfo layout

-- | The class that lets us display a sample input or output in the
--   supported content-types when generating documentation for endpoints
--   that either:
--   
--   <ul>
--   <li>expect a request body, or</li>
--   <li>return a non empty response body</li>
--   </ul>
--   
--   Example of an instance:
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric #-}
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   import Data.Aeson
--   import Data.Text
--   import GHC.Generics
--   
--   data Greet = Greet { _msg :: Text }
--     deriving (Generic, Show)
--   
--   instance FromJSON Greet
--   instance ToJSON Greet
--   
--   instance ToSample Greet Greet where
--     toSample _ = Just g
--   
--       where g = Greet "Hello, haskeller!"
--   </pre>
--   
--   You can also instantiate this class using <a>toSamples</a> instead of
--   <a>toSample</a>: it lets you specify different responses along with
--   some context (as <a>Text</a>) that explains when you're supposed to
--   get the corresponding response.
class ToSample a b | a -> b where toSample _ = snd <$> listToMaybe samples where samples = toSamples (Proxy :: Proxy a) toSamples _ = maybe [] (return . ("",)) s where s = toSample (Proxy :: Proxy a)
toSample :: ToSample a b => Proxy a -> Maybe b
toSamples :: ToSample a b => Proxy a -> [(Text, b)]

-- | Synthesise a sample value of a type, encoded in the specified media
--   types.
sampleByteString :: (ToSample a b, IsNonEmpty ctypes, AllMimeRender ctypes b) => Proxy ctypes -> Proxy a -> [(MediaType, ByteString)]

-- | Synthesise a list of sample values of a particular type, encoded in
--   the specified media types.
sampleByteStrings :: (ToSample a b, IsNonEmpty ctypes, AllMimeRender ctypes b) => Proxy ctypes -> Proxy a -> [(Text, MediaType, ByteString)]

-- | The class that helps us automatically get documentation for GET
--   parameters.
--   
--   Example of an instance:
--   
--   <pre>
--   instance ToParam (QueryParam "capital" Bool) where
--     toParam _ =
--       DocQueryParam "capital"
--                     ["true", "false"]
--                     "Get the greeting message in uppercase (true) or not (false). Default is false."
--   </pre>
class ToParam t
toParam :: ToParam t => Proxy t -> DocQueryParam

-- | The class that helps us automatically get documentation for URL
--   captures.
--   
--   Example of an instance:
--   
--   <pre>
--   instance ToCapture (Capture "name" Text) where
--     toCapture _ = DocCapture "name" "name of the person to greet"
--   </pre>
class ToCapture c
toCapture :: ToCapture c => Proxy c -> DocCapture

-- | Supported HTTP request methods
data Method

-- | the DELETE method
DocDELETE :: Method

-- | the GET method
DocGET :: Method

-- | the POST method
DocPOST :: Method

-- | the PUT method
DocPUT :: Method

-- | An <a>Endpoint</a> type that holds the <a>path</a> and the
--   <a>method</a>.
--   
--   Gets used as the key in the <a>API</a> hashmap. Modify
--   <a>defEndpoint</a> or any <a>Endpoint</a> value you want using the
--   <a>path</a> and <a>method</a> lenses to tweak.
--   
--   <pre>
--   λ&gt; <a>defEndpoint</a>
--   GET /
--   λ&gt; <a>defEndpoint</a> &amp; <a>path</a> <a>&lt;&gt;~</a> ["foo"]
--   GET /foo
--   λ&gt; <a>defEndpoint</a> &amp; <a>path</a> <a>&lt;&gt;~</a> ["foo"] &amp; <a>method</a> <a>.~</a> <a>DocPOST</a>
--   POST /foo
--   </pre>
data Endpoint
path :: Lens' Endpoint [String]
method :: Lens' Endpoint Method

-- | An <a>Endpoint</a> whose path is `"/"` and whose method is
--   <a>DocGET</a>
--   
--   Here's how you can modify it:
--   
--   <pre>
--   λ&gt; <a>defEndpoint</a>
--   GET /
--   λ&gt; <a>defEndpoint</a> &amp; <a>path</a> <a>&lt;&gt;~</a> ["foo"]
--   GET /foo
--   λ&gt; <a>defEndpoint</a> &amp; <a>path</a> <a>&lt;&gt;~</a> ["foo"] &amp; <a>method</a> <a>.~</a> <a>DocPOST</a>
--   POST /foo
--   </pre>
defEndpoint :: Endpoint

-- | Our API documentation type, a product of top-level information and a
--   good old hashmap from <a>Endpoint</a> to <a>Action</a>
data API
apiIntros :: Lens' API [DocIntro]
apiEndpoints :: Lens' API (HashMap Endpoint Action)

-- | An empty <a>API</a>
emptyAPI :: API

-- | A type to represent captures. Holds the name of the capture and a
--   description.
--   
--   Write a <a>ToCapture</a> instance for your captured types.
data DocCapture
DocCapture :: String -> String -> DocCapture
_capSymbol :: DocCapture -> String
_capDesc :: DocCapture -> String
capSymbol :: Lens' DocCapture String
capDesc :: Lens' DocCapture String

-- | A type to represent a <i>GET</i> parameter from the Query String.
--   Holds its name, the possible values (leave empty if there isn't a
--   finite number of them), and a description of how it influences the
--   output or behavior.
--   
--   Write a <a>ToParam</a> instance for your GET parameter types
data DocQueryParam
DocQueryParam :: String -> [String] -> String -> ParamKind -> DocQueryParam
_paramName :: DocQueryParam -> String
_paramValues :: DocQueryParam -> [String]
_paramDesc :: DocQueryParam -> String
_paramKind :: DocQueryParam -> ParamKind

-- | Type of GET parameter:
--   
--   <ul>
--   <li>Normal corresponds to <tt>QueryParam</tt>, i.e your usual GET
--   parameter</li>
--   <li>List corresponds to <tt>QueryParams</tt>, i.e GET parameters with
--   multiple values</li>
--   <li>Flag corresponds to <tt>QueryFlag</tt>, i.e a value-less GET
--   parameter</li>
--   </ul>
data ParamKind
Normal :: ParamKind
List :: ParamKind
Flag :: ParamKind
paramName :: Lens' DocQueryParam String
paramValues :: Lens' DocQueryParam [String]
paramDesc :: Lens' DocQueryParam String
paramKind :: Lens' DocQueryParam ParamKind

-- | A type to represent extra notes that may be attached to an
--   <a>Action</a>.
--   
--   This is intended to be used when writing your own HasDocs instances to
--   add extra sections to your endpoint's documentation.
data DocNote
DocNote :: String -> [String] -> DocNote
_noteTitle :: DocNote -> String
_noteBody :: DocNote -> [String]
noteTitle :: Lens' DocNote String
noteBody :: Lens' DocNote [String]

-- | An introductory paragraph for your documentation. You can pass these
--   to <a>docsWithIntros</a>.
data DocIntro
DocIntro :: String -> [String] -> DocIntro

-- | Appears above the intro blob
_introTitle :: DocIntro -> String

-- | Each String is a paragraph.
_introBody :: DocIntro -> [String]
introTitle :: Lens' DocIntro String
introBody :: Lens' DocIntro [String]

-- | A type to represent an HTTP response. Has an <a>Int</a> status, a list
--   of possible <tt>MediaType</tt>s, and a list of example
--   <a>ByteString</a> response bodies. Tweak <a>defResponse</a> using the
--   <a>respStatus</a>, <a>respTypes</a> and <a>respBody</a> lenses if you
--   want.
--   
--   If you want to respond with a non-empty response body, you'll most
--   likely want to write a <a>ToSample</a> instance for the type that'll
--   be represented as encoded data in the response.
--   
--   Can be tweaked with three lenses.
--   
--   <pre>
--   λ&gt; defResponse
--   Response {_respStatus = 200, _respTypes = [], _respBody = []}
--   λ&gt; defResponse &amp; respStatus .~ 204 &amp; respBody .~ [("If everything goes well", "{ \"status\": \"ok\" }")]
--   Response {_respStatus = 204, _respTypes = [], _respBody = [("If everything goes well", "{ \"status\": \"ok\" }")]}
--   </pre>
data Response
Response :: Int -> [MediaType] -> [(Text, MediaType, ByteString)] -> [Header] -> Response
_respStatus :: Response -> Int
_respTypes :: Response -> [MediaType]
_respBody :: Response -> [(Text, MediaType, ByteString)]
_respHeaders :: Response -> [Header]
respStatus :: Lens' Response Int
respTypes :: Lens' Response [MediaType]
respBody :: Lens' Response [(Text, MediaType, ByteString)]

-- | Default response: status code 200, no response body.
--   
--   Can be tweaked with two lenses.
--   
--   <pre>
--   λ&gt; defResponse
--   Response {_respStatus = 200, _respBody = Nothing}
--   λ&gt; defResponse &amp; respStatus .~ 204 &amp; respBody .~ Just "[]"
--   Response {_respStatus = 204, _respBody = Just "[]"}
--   </pre>
defResponse :: Response

-- | A datatype that represents everything that can happen at an endpoint,
--   with its lenses:
--   
--   <ul>
--   <li>List of captures (<a>captures</a>)</li>
--   <li>List of GET parameters (<a>params</a>)</li>
--   <li>What the request body should look like, if any is requested
--   (<a>rqbody</a>)</li>
--   <li>What the response should be if everything goes well
--   (<a>response</a>)</li>
--   </ul>
--   
--   You can tweak an <a>Action</a> (like the default <a>defAction</a>)
--   with these lenses to transform an action and add some information to
--   it.
data Action
captures :: Lens' Action [DocCapture]
headers :: Lens' Action [Text]
notes :: Lens' Action [DocNote]
params :: Lens' Action [DocQueryParam]
rqtypes :: Lens' Action [MediaType]
rqbody :: Lens' Action [(MediaType, ByteString)]
response :: Lens' Action Response
defAction :: Action

-- | Create an API that's comprised of a single endpoint. <a>API</a> is a
--   <a>Monoid</a>, so combine multiple endpoints with <a>mappend</a> or
--   <a>&lt;&gt;</a>.
single :: Endpoint -> Action -> API