From 1fef813a3bd2f7dcb2ce58483869001c47bc78b4 Mon Sep 17 00:00:00 2001 From: Matthias Fischmann Date: Mon, 23 Feb 2015 10:53:18 +0100 Subject: [PATCH 1/3] Render entpoints in canonical order. --- src/Servant/Docs.hs | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/src/Servant/Docs.hs b/src/Servant/Docs.hs index 6f3e2cdf..936a8020 100644 --- a/src/Servant/Docs.hs +++ b/src/Servant/Docs.hs @@ -11,6 +11,7 @@ {-# LANGUAGE ConstraintKinds #-} {-# LANGUAGE UndecidableInstances #-} {-# LANGUAGE PolyKinds #-} +{-# LANGUAGE StandaloneDeriving #-} ------------------------------------------------------------------------------- -- | This module lets you get API docs for free. It lets generate @@ -190,6 +191,7 @@ import Data.ByteString.Lazy.Char8 (ByteString) import Data.Hashable import Data.HashMap.Strict (HashMap) import Data.List +import Data.Function (on) import Data.Maybe import Data.Monoid import Data.Ord (comparing) @@ -207,12 +209,18 @@ import qualified Data.HashMap.Strict as HM import qualified Data.Text as T import qualified Network.HTTP.Media as M +-- | Temporary orphan. Can be eliminated as soon as +-- https://github.com/zmthy/http-media/pull/12 has been released. +-- (Also consider removing StandaloneDeriving language ext above.) +instance Ord M.MediaType where + compare t t' = compare (show t) (show t') + -- | Supported HTTP request methods data Method = DocDELETE -- ^ the DELETE method | DocGET -- ^ the GET method | DocPOST -- ^ the POST method | DocPUT -- ^ the PUT method - deriving (Eq, Generic) + deriving (Eq, Ord, Generic) instance Show Method where show DocGET = "GET" @@ -239,7 +247,7 @@ instance Hashable Method data Endpoint = Endpoint { _path :: [String] -- type collected , _method :: Method -- type collected - } deriving (Eq, Generic) + } deriving (Eq, Ord, Generic) instance Show Endpoint where show (Endpoint p m) = @@ -291,7 +299,7 @@ emptyAPI = mempty data DocCapture = DocCapture { _capSymbol :: String -- type supplied , _capDesc :: String -- user supplied - } deriving (Eq, Show) + } deriving (Eq, Ord, Show) -- | A type to represent a /GET/ parameter from the Query String. Holds its name, -- the possible values (leave empty if there isn't a finite number of them), @@ -303,7 +311,7 @@ data DocQueryParam = DocQueryParam , _paramValues :: [String] -- user supplied , _paramDesc :: String -- user supplied , _paramKind :: ParamKind - } deriving (Eq, Show) + } deriving (Eq, Ord, Show) -- | An introductory paragraph for your documentation. You can pass these to -- 'docsWithIntros'. @@ -322,7 +330,7 @@ instance Ord DocIntro where data DocNote = DocNote { _noteTitle :: String , _noteBody :: [String] - } deriving (Eq, Show) + } deriving (Eq, Ord, Show) -- | Type of extra information that a user may wish to "union" with their -- documentation. @@ -341,7 +349,7 @@ instance Monoid (ExtraInfo a) where -- - List corresponds to @QueryParams@, i.e GET parameters with multiple values -- - Flag corresponds to @QueryFlag@, i.e a value-less GET parameter data ParamKind = Normal | List | Flag - deriving (Eq, Show) + deriving (Eq, Ord, Show) -- | A type to represent an HTTP response. Has an 'Int' status, a list of -- possible 'MediaType's, and a list of example 'ByteString' response bodies. @@ -362,7 +370,7 @@ data Response = Response { _respStatus :: Int , _respTypes :: [M.MediaType] , _respBody :: [(Text, M.MediaType, ByteString)] - } deriving (Eq, Show) + } deriving (Eq, Ord, Show) -- | Default response: status code 200, no response body. -- @@ -394,7 +402,7 @@ data Action = Action , _rqtypes :: [M.MediaType] -- type collected , _rqbody :: [(M.MediaType, ByteString)] -- user supplied , _response :: Response -- user supplied - } deriving (Eq, Show) + } deriving (Eq, Ord, Show) -- | Combine two Actions, we can't make a monoid as merging Response breaks the -- laws. @@ -611,7 +619,7 @@ class ToCapture c where markdown :: API -> String markdown api = unlines $ introsStr (api ^. apiIntros) - ++ (concatMap (uncurry printEndpoint) . HM.toList $ api ^. apiEndpoints) + ++ (concatMap (uncurry printEndpoint) . sort . HM.toList $ api ^. apiEndpoints) where printEndpoint :: Endpoint -> Action -> [String] printEndpoint endpoint action = From f11d5207e412670a1573aa3e2b58d2ff8d4148e1 Mon Sep 17 00:00:00 2001 From: Matthias Fischmann Date: Tue, 24 Feb 2015 08:54:14 +0100 Subject: [PATCH 2/3] Dropped orphan instance for MediaType (now available upstream). --- servant-docs.cabal | 2 +- src/Servant/Docs.hs | 6 ------ 2 files changed, 1 insertion(+), 7 deletions(-) diff --git a/servant-docs.cabal b/servant-docs.cabal index 32c18230..48e5271c 100644 --- a/servant-docs.cabal +++ b/servant-docs.cabal @@ -31,7 +31,7 @@ library , aeson , bytestring , hashable - , http-media + , http-media >= 0.6 , lens , servant >= 0.2.1 , string-conversions diff --git a/src/Servant/Docs.hs b/src/Servant/Docs.hs index 936a8020..945f1e62 100644 --- a/src/Servant/Docs.hs +++ b/src/Servant/Docs.hs @@ -209,12 +209,6 @@ import qualified Data.HashMap.Strict as HM import qualified Data.Text as T import qualified Network.HTTP.Media as M --- | Temporary orphan. Can be eliminated as soon as --- https://github.com/zmthy/http-media/pull/12 has been released. --- (Also consider removing StandaloneDeriving language ext above.) -instance Ord M.MediaType where - compare t t' = compare (show t) (show t') - -- | Supported HTTP request methods data Method = DocDELETE -- ^ the DELETE method | DocGET -- ^ the GET method From 68fee749c4e5f7136ead94338b6a783788f2c6a4 Mon Sep 17 00:00:00 2001 From: Matthias Fischmann Date: Tue, 24 Feb 2015 11:01:34 +0100 Subject: [PATCH 3/3] Remove dead code. --- src/Servant/Docs.hs | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/Servant/Docs.hs b/src/Servant/Docs.hs index 945f1e62..7cf9f441 100644 --- a/src/Servant/Docs.hs +++ b/src/Servant/Docs.hs @@ -11,7 +11,6 @@ {-# LANGUAGE ConstraintKinds #-} {-# LANGUAGE UndecidableInstances #-} {-# LANGUAGE PolyKinds #-} -{-# LANGUAGE StandaloneDeriving #-} ------------------------------------------------------------------------------- -- | This module lets you get API docs for free. It lets generate @@ -191,7 +190,6 @@ import Data.ByteString.Lazy.Char8 (ByteString) import Data.Hashable import Data.HashMap.Strict (HashMap) import Data.List -import Data.Function (on) import Data.Maybe import Data.Monoid import Data.Ord (comparing)