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


-- | generate API docs for your servant webservice
--   
--   Library for generating API docs from a servant API definition.
--   
--   Runnable example <a>here</a>.
--   
--   <a>CHANGELOG</a>
@package servant-docs
@version 0.4.4.7

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 Servant.Docs.Internal.ToSample a b => Servant.Docs.Internal.ToSample (Servant.API.ResponseHeaders.Headers ls a) b
instance Servant.Docs.Internal.AllHeaderSamples '[]
instance (Data.ByteString.Conversion.To.ToByteString l, Servant.Docs.Internal.AllHeaderSamples ls, Servant.Docs.Internal.ToSample l l, GHC.TypeLits.KnownSymbol h) => Servant.Docs.Internal.AllHeaderSamples (Servant.API.Header.Header h l : ls)
instance Servant.Docs.Internal.SupportedTypes '[]
instance (Servant.API.ContentTypes.Accept ctype, Servant.Docs.Internal.SupportedTypes rest) => Servant.Docs.Internal.SupportedTypes (ctype : rest)
instance (Servant.Docs.Internal.HasDocs layout1, Servant.Docs.Internal.HasDocs layout2) => Servant.Docs.Internal.HasDocs (layout1 Servant.API.Alternative.:<|> layout2)
instance forall (k :: BOX) (k1 :: BOX) (sym :: GHC.TypeLits.Symbol) (a :: k1) (sublayout :: k). (GHC.TypeLits.KnownSymbol sym, Servant.Docs.Internal.ToCapture (Servant.API.Capture.Capture sym a), Servant.Docs.Internal.HasDocs sublayout) => Servant.Docs.Internal.HasDocs (Servant.API.Capture.Capture sym a Servant.API.Sub.:> sublayout)
instance (Servant.Docs.Internal.ToSample a b, Servant.API.ContentTypes.IsNonEmpty cts, Servant.API.ContentTypes.AllMimeRender cts b, Servant.Docs.Internal.SupportedTypes cts) => Servant.Docs.Internal.HasDocs (Servant.API.Delete.Delete cts a)
instance (Servant.Docs.Internal.ToSample a b, Servant.API.ContentTypes.IsNonEmpty cts, Servant.API.ContentTypes.AllMimeRender cts b, Servant.Docs.Internal.SupportedTypes cts, Servant.Docs.Internal.AllHeaderSamples ls, Servant.API.ResponseHeaders.GetHeaders (Servant.API.ResponseHeaders.HList ls)) => Servant.Docs.Internal.HasDocs (Servant.API.Delete.Delete cts (Servant.API.ResponseHeaders.Headers ls a))
instance (Servant.Docs.Internal.ToSample a b, Servant.API.ContentTypes.IsNonEmpty cts, Servant.API.ContentTypes.AllMimeRender cts b, Servant.Docs.Internal.SupportedTypes cts) => Servant.Docs.Internal.HasDocs (Servant.API.Get.Get cts a)
instance (Servant.Docs.Internal.ToSample a b, Servant.API.ContentTypes.IsNonEmpty cts, Servant.API.ContentTypes.AllMimeRender cts b, Servant.Docs.Internal.SupportedTypes cts, Servant.Docs.Internal.AllHeaderSamples ls, Servant.API.ResponseHeaders.GetHeaders (Servant.API.ResponseHeaders.HList ls)) => Servant.Docs.Internal.HasDocs (Servant.API.Get.Get cts (Servant.API.ResponseHeaders.Headers ls a))
instance forall (k :: BOX) (sym :: GHC.TypeLits.Symbol) a (sublayout :: k). (GHC.TypeLits.KnownSymbol sym, Servant.Docs.Internal.HasDocs sublayout) => Servant.Docs.Internal.HasDocs (Servant.API.Header.Header sym a Servant.API.Sub.:> sublayout)
instance (Servant.Docs.Internal.ToSample a b, Servant.API.ContentTypes.IsNonEmpty cts, Servant.API.ContentTypes.AllMimeRender cts b, Servant.Docs.Internal.SupportedTypes cts) => Servant.Docs.Internal.HasDocs (Servant.API.Post.Post cts a)
instance (Servant.Docs.Internal.ToSample a b, Servant.API.ContentTypes.IsNonEmpty cts, Servant.API.ContentTypes.AllMimeRender cts b, Servant.Docs.Internal.SupportedTypes cts, Servant.Docs.Internal.AllHeaderSamples ls, Servant.API.ResponseHeaders.GetHeaders (Servant.API.ResponseHeaders.HList ls)) => Servant.Docs.Internal.HasDocs (Servant.API.Post.Post cts (Servant.API.ResponseHeaders.Headers ls a))
instance (Servant.Docs.Internal.ToSample a b, Servant.API.ContentTypes.IsNonEmpty cts, Servant.API.ContentTypes.AllMimeRender cts b, Servant.Docs.Internal.SupportedTypes cts) => Servant.Docs.Internal.HasDocs (Servant.API.Put.Put cts a)
instance (Servant.Docs.Internal.ToSample a b, Servant.API.ContentTypes.IsNonEmpty cts, Servant.API.ContentTypes.AllMimeRender cts b, Servant.Docs.Internal.SupportedTypes cts, Servant.Docs.Internal.AllHeaderSamples ls, Servant.API.ResponseHeaders.GetHeaders (Servant.API.ResponseHeaders.HList ls)) => Servant.Docs.Internal.HasDocs (Servant.API.Put.Put cts (Servant.API.ResponseHeaders.Headers ls a))
instance forall (k :: BOX) (k1 :: BOX) (sym :: GHC.TypeLits.Symbol) (a :: k1) (sublayout :: k). (GHC.TypeLits.KnownSymbol sym, Servant.Docs.Internal.ToParam (Servant.API.QueryParam.QueryParam sym a), Servant.Docs.Internal.HasDocs sublayout) => Servant.Docs.Internal.HasDocs (Servant.API.QueryParam.QueryParam sym a Servant.API.Sub.:> sublayout)
instance forall (k :: BOX) (k1 :: BOX) (sym :: GHC.TypeLits.Symbol) (a :: k1) (sublayout :: k). (GHC.TypeLits.KnownSymbol sym, Servant.Docs.Internal.ToParam (Servant.API.QueryParam.QueryParams sym a), Servant.Docs.Internal.HasDocs sublayout) => Servant.Docs.Internal.HasDocs (Servant.API.QueryParam.QueryParams sym a Servant.API.Sub.:> sublayout)
instance forall (k :: BOX) (sym :: GHC.TypeLits.Symbol) (sublayout :: k). (GHC.TypeLits.KnownSymbol sym, Servant.Docs.Internal.ToParam (Servant.API.QueryParam.QueryFlag sym), Servant.Docs.Internal.HasDocs sublayout) => Servant.Docs.Internal.HasDocs (Servant.API.QueryParam.QueryFlag sym Servant.API.Sub.:> sublayout)
instance forall (k :: BOX) (k1 :: BOX) (sym :: GHC.TypeLits.Symbol) (a :: k1) (sublayout :: k). (GHC.TypeLits.KnownSymbol sym, Servant.Docs.Internal.ToParam (Servant.API.MatrixParam.MatrixParam sym a), Servant.Docs.Internal.HasDocs sublayout) => Servant.Docs.Internal.HasDocs (Servant.API.MatrixParam.MatrixParam sym a Servant.API.Sub.:> sublayout)
instance forall (k :: BOX) (k1 :: BOX) (sym :: GHC.TypeLits.Symbol) (a :: k1) (sublayout :: k). (GHC.TypeLits.KnownSymbol sym, Servant.Docs.Internal.HasDocs sublayout) => Servant.Docs.Internal.HasDocs (Servant.API.MatrixParam.MatrixParams sym a Servant.API.Sub.:> sublayout)
instance forall (k :: BOX) (sym :: GHC.TypeLits.Symbol) (sublayout :: k). (GHC.TypeLits.KnownSymbol sym, Servant.Docs.Internal.HasDocs sublayout) => Servant.Docs.Internal.HasDocs (Servant.API.MatrixParam.MatrixFlag sym Servant.API.Sub.:> sublayout)
instance Servant.Docs.Internal.HasDocs Servant.API.Raw.Raw
instance forall (k :: BOX) (k1 :: BOX) (cts :: [*]) (a :: k1) (sublayout :: k) b. (Servant.Docs.Internal.ToSample a b, Servant.API.ContentTypes.IsNonEmpty cts, Servant.API.ContentTypes.AllMimeRender cts b, Servant.Docs.Internal.HasDocs sublayout, Servant.Docs.Internal.SupportedTypes cts) => Servant.Docs.Internal.HasDocs (Servant.API.ReqBody.ReqBody cts a Servant.API.Sub.:> sublayout)
instance forall (k :: BOX) (path :: GHC.TypeLits.Symbol) (sublayout :: k). (GHC.TypeLits.KnownSymbol path, Servant.Docs.Internal.HasDocs sublayout) => Servant.Docs.Internal.HasDocs (path Servant.API.Sub.:> sublayout)
instance GHC.Generics.Selector Servant.Docs.Internal.S1_0_1Endpoint
instance GHC.Generics.Selector Servant.Docs.Internal.S1_0_0Endpoint
instance GHC.Generics.Constructor Servant.Docs.Internal.C1_0Endpoint
instance GHC.Generics.Datatype Servant.Docs.Internal.D1Endpoint
instance GHC.Generics.Constructor Servant.Docs.Internal.C1_3Method
instance GHC.Generics.Constructor Servant.Docs.Internal.C1_2Method
instance GHC.Generics.Constructor Servant.Docs.Internal.C1_1Method
instance GHC.Generics.Constructor Servant.Docs.Internal.C1_0Method
instance GHC.Generics.Datatype Servant.Docs.Internal.D1Method
instance GHC.Show.Show Servant.Docs.Internal.API
instance GHC.Classes.Eq Servant.Docs.Internal.API
instance GHC.Show.Show Servant.Docs.Internal.Action
instance GHC.Classes.Ord Servant.Docs.Internal.Action
instance GHC.Classes.Eq Servant.Docs.Internal.Action
instance GHC.Show.Show Servant.Docs.Internal.Response
instance GHC.Classes.Ord Servant.Docs.Internal.Response
instance GHC.Classes.Eq Servant.Docs.Internal.Response
instance GHC.Show.Show Servant.Docs.Internal.DocQueryParam
instance GHC.Classes.Ord Servant.Docs.Internal.DocQueryParam
instance GHC.Classes.Eq Servant.Docs.Internal.DocQueryParam
instance GHC.Show.Show Servant.Docs.Internal.ParamKind
instance GHC.Classes.Ord Servant.Docs.Internal.ParamKind
instance GHC.Classes.Eq Servant.Docs.Internal.ParamKind
instance GHC.Show.Show Servant.Docs.Internal.DocNote
instance GHC.Classes.Ord Servant.Docs.Internal.DocNote
instance GHC.Classes.Eq Servant.Docs.Internal.DocNote
instance GHC.Show.Show Servant.Docs.Internal.DocIntro
instance GHC.Classes.Eq Servant.Docs.Internal.DocIntro
instance GHC.Show.Show Servant.Docs.Internal.DocCapture
instance GHC.Classes.Ord Servant.Docs.Internal.DocCapture
instance GHC.Classes.Eq Servant.Docs.Internal.DocCapture
instance GHC.Generics.Generic Servant.Docs.Internal.Endpoint
instance GHC.Classes.Ord Servant.Docs.Internal.Endpoint
instance GHC.Classes.Eq Servant.Docs.Internal.Endpoint
instance GHC.Generics.Generic Servant.Docs.Internal.Method
instance GHC.Classes.Ord Servant.Docs.Internal.Method
instance GHC.Classes.Eq Servant.Docs.Internal.Method
instance GHC.Show.Show Servant.Docs.Internal.Method
instance Data.Hashable.Class.Hashable Servant.Docs.Internal.Method
instance GHC.Show.Show Servant.Docs.Internal.Endpoint
instance Data.Hashable.Class.Hashable Servant.Docs.Internal.Endpoint
instance GHC.Base.Monoid Servant.Docs.Internal.API
instance GHC.Classes.Ord Servant.Docs.Internal.DocIntro
instance forall (k :: BOX) (a :: k). GHC.Base.Monoid (Servant.Docs.Internal.ExtraInfo a)


-- | 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