servant-docs 0.3 → 0.3.1
raw patch · 3 files changed
+81/−10 lines, 3 filesnew-uploader
Files
- example/greet.hs +8/−1
- servant-docs.cabal +2/−2
- src/Servant/Docs.hs +71/−7
example/greet.hs view
@@ -36,6 +36,13 @@ "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 where toSample = Just $ Greet "Hello, haskeller!" @@ -47,7 +54,7 @@ -- API specification type TestApi = -- GET /hello/:name?capital={true, false} returns a Greet as JSON- "hello" :> Capture "name" Text :> QueryParam "capital" Bool :> Get Greet+ "hello" :> MatrixParam "lang" String :> Capture "name" Text :> QueryParam "capital" Bool :> Get Greet -- POST /greet with a Greet as JSON in the request body, -- returns a Greet as JSON
servant-docs.cabal view
@@ -1,5 +1,5 @@ name: servant-docs-version: 0.3+version: 0.3.1 synopsis: generate API docs for your servant webservice description: Library for generating API docs from a servant API definition.@@ -33,7 +33,7 @@ , bytestring , hashable , lens- , servant >= 0.2.1+ , servant >= 0.2.1 && < 0.3 , string-conversions , system-filepath , text
src/Servant/Docs.hs view
@@ -216,6 +216,7 @@ , _paramKind :: ParamKind } deriving (Eq, Show) + -- | Type of GET parameter: -- -- - Normal corresponds to @QueryParam@, i.e your usual GET parameter@@ -265,11 +266,12 @@ -- You can tweak an 'Action' (like the default 'defAction') with these lenses -- to transform an action and add some information to it. data Action = Action- { _captures :: [DocCapture] -- type collected + user supplied info- , _headers :: [Text] -- type collected- , _params :: [DocQueryParam] -- type collected + user supplied info- , _rqbody :: Maybe ByteString -- user supplied- , _response :: Response -- user supplied+ { _captures :: [DocCapture] -- type collected + user supplied info+ , _headers :: [Text] -- type collected+ , _params :: [DocQueryParam] -- type collected + user supplied info+ , _mxParams :: [(String, [DocQueryParam])] -- type collected + user supplied info+ , _rqbody :: Maybe ByteString -- user supplied+ , _response :: Response -- user supplied } deriving (Eq, Show) -- Default 'Action'. Has no 'captures', no GET 'params', expects@@ -278,14 +280,15 @@ -- Tweakable with lenses. -- -- > λ> defAction--- > Action {_captures = [], _params = [], _rqbody = Nothing, _response = Response {_respStatus = 200, _respBody = Nothing}}+-- > Action {_captures = [], _headers = [], _params = [], _mxParams = [], _rqbody = Nothing, _response = Response {_respStatus = 200, _respBody = Nothing}} -- > λ> defAction & response.respStatus .~ 201--- > Action {_captures = [], _params = [], _rqbody = Nothing, _response = Response {_respStatus = 201, _respBody = Nothing}}+-- > Action {_captures = [], _headers = [], _params = [], _mxParams = [], _rqbody = Nothing, _response = Response {_respStatus = 201, _respBody = Nothing}} defAction :: Action defAction = Action [] [] []+ [] Nothing defResponse @@ -393,6 +396,7 @@ replicate len '-' : "" : capturesStr (action ^. captures) +++ mxParamsStr (action ^. mxParams) ++ headersStr (action ^. headers) ++ paramsStr (action ^. params) ++ rqbodyStr (action ^. rqbody) ++@@ -413,6 +417,22 @@ captureStr cap = "- *" ++ (cap ^. capSymbol) ++ "*: " ++ (cap ^. capDesc) + mxParamsStr :: [(String, [DocQueryParam])] -> [String]+ mxParamsStr [] = []+ mxParamsStr l =+ "**Matrix Parameters**: " :+ "" :+ map segmentStr l +++ "" :+ []+ segmentStr :: (String, [DocQueryParam]) -> String+ segmentStr (segment, l) = unlines $+ ("**" ++ segment ++ "**: ") :+ "" :+ map paramStr l +++ "" :+ []+ headersStr :: [Text] -> [String] headersStr [] = [] headersStr l = [""] ++ map headerStr l ++ [""]@@ -582,6 +602,50 @@ where sublayoutP = Proxy :: Proxy sublayout paramP = Proxy :: Proxy (QueryFlag sym) action' = over params (|> toParam paramP) action+++instance (KnownSymbol sym, ToParam (MatrixParam sym a), HasDocs sublayout)+ => HasDocs (MatrixParam sym a :> sublayout) where++ docsFor Proxy (endpoint, action) =+ docsFor sublayoutP (endpoint', action')++ where sublayoutP = Proxy :: Proxy sublayout+ paramP = Proxy :: Proxy (MatrixParam sym a)+ segment = endpoint ^. (path._last)+ segment' = action ^. (mxParams._last._1)+ endpoint' = over (path._last) (\p -> p ++ ";" ++ symbolVal symP ++ "=<value>") endpoint++ action' = if segment' /= segment+ -- This is the first matrix parameter for this segment, insert a new entry into the mxParams list+ then over mxParams (|> (segment, [toParam paramP])) action+ -- We've already inserted a matrix parameter for this segment, append to the existing list+ else action & mxParams._last._2 <>~ [toParam paramP]+ symP = Proxy :: Proxy sym+++instance (KnownSymbol sym, {- ToParam (MatrixParams sym a), -} HasDocs sublayout)+ => HasDocs (MatrixParams sym a :> sublayout) where++ docsFor Proxy (endpoint, action) =+ docsFor sublayoutP (endpoint', action)++ where sublayoutP = Proxy :: Proxy sublayout+ endpoint' = over path (\p -> p ++ [";" ++ symbolVal symP ++ "=<value>"]) endpoint+ symP = Proxy :: Proxy sym+++instance (KnownSymbol sym, {- ToParam (MatrixFlag sym), -} HasDocs sublayout)+ => HasDocs (MatrixFlag sym :> sublayout) where++ docsFor Proxy (endpoint, action) =+ docsFor sublayoutP (endpoint', action)++ where sublayoutP = Proxy :: Proxy sublayout++ endpoint' = over path (\p -> p ++ [";" ++ symbolVal symP]) endpoint+ symP = Proxy :: Proxy sym+ instance HasDocs Raw where docsFor _proxy (endpoint, action) =