1fef813 · typeable/servant

git.iko.soy/typeable/servant

on master help sign in

Render entpoints in canonical order.

1fef813Matthias Fischmann12 years ago

src/Servant/Docs.hs+17−9

compare with master

unifiedsplit

@@ -11,6 +11,7 @@

11{-# LANGUAGE ConstraintKinds #-}

12{-# LANGUAGE UndecidableInstances #-}

13{-# LANGUAGE PolyKinds #-}

14+{-# LANGUAGE StandaloneDeriving #-}

15-------------------------------------------------------------------------------

16-------------------------------------------------------------------------------

16-- | This module lets you get API docs for free. It lets generate

17-- | This module lets you get API docs for free. It lets generate

@@ -190,6 +191,7 @@ import Data.ByteString.Lazy.Char8 (ByteString)

190import Data.Hashable

191import Data.Hashable

191import Data.HashMap.Strict (HashMap)

192import Data.HashMap.Strict (HashMap)

192import Data.List

193import Data.List

194+import Data.Function (on)

193import Data.Maybe

195import Data.Maybe

194import Data.Monoid

196import Data.Monoid

195import Data.Ord (comparing)

197import Data.Ord (comparing)

@@ -207,12 +209,18 @@ import qualified Data.HashMap.Strict as HM

207import qualified Data.Text as T

209import qualified Data.Text as T

208import qualified Network.HTTP.Media as M

210import qualified Network.HTTP.Media as M

209

211

212+-- | Temporary orphan. Can be eliminated as soon as

213+-- https://github.com/zmthy/http-media/pull/12 has been released.

214+-- (Also consider removing StandaloneDeriving language ext above.)

215+instance Ord M.MediaType where

216+ compare t t' = compare (show t) (show t')

217+

210-- | Supported HTTP request methods

218-- | Supported HTTP request methods

211data Method = DocDELETE -- ^ the DELETE method

219data Method = DocDELETE -- ^ the DELETE method

212 | DocGET -- ^ the GET method

220 | DocGET -- ^ the GET method

213 | DocPOST -- ^ the POST method

221 | DocPOST -- ^ the POST method

214 | DocPUT -- ^ the PUT method

222 | DocPUT -- ^ the PUT method

215− deriving (Eq, Generic)

223+ deriving (Eq, Ord, Generic)

216

224

217instance Show Method where

225instance Show Method where

218 show DocGET = "GET"

226 show DocGET = "GET"

@@ -239,7 +247,7 @@ instance Hashable Method

239data Endpoint = Endpoint

247data Endpoint = Endpoint

240 { _path :: [String] -- type collected

248 { _path :: [String] -- type collected

241 , _method :: Method -- type collected

249 , _method :: Method -- type collected

242− } deriving (Eq, Generic)

250+ } deriving (Eq, Ord, Generic)

243

251

244instance Show Endpoint where

252instance Show Endpoint where

245 show (Endpoint p m) =

253 show (Endpoint p m) =

@@ -291,7 +299,7 @@ emptyAPI = mempty

291data DocCapture = DocCapture

299data DocCapture = DocCapture

292 { _capSymbol :: String -- type supplied

300 { _capSymbol :: String -- type supplied

293 , _capDesc :: String -- user supplied

301 , _capDesc :: String -- user supplied

294− } deriving (Eq, Show)

302+ } deriving (Eq, Ord, Show)

295

303

296-- | A type to represent a /GET/ parameter from the Query String. Holds its name,

304-- | A type to represent a /GET/ parameter from the Query String. Holds its name,

297-- the possible values (leave empty if there isn't a finite number of them),

305-- the possible values (leave empty if there isn't a finite number of them),

@@ -303,7 +311,7 @@ data DocQueryParam = DocQueryParam

303 , _paramValues :: [String] -- user supplied

311 , _paramValues :: [String] -- user supplied

304 , _paramDesc :: String -- user supplied

312 , _paramDesc :: String -- user supplied

305 , _paramKind :: ParamKind

313 , _paramKind :: ParamKind

306− } deriving (Eq, Show)

314+ } deriving (Eq, Ord, Show)

307

315

308-- | An introductory paragraph for your documentation. You can pass these to

316-- | An introductory paragraph for your documentation. You can pass these to

309-- 'docsWithIntros'.

317-- 'docsWithIntros'.

@@ -322,7 +330,7 @@ instance Ord DocIntro where

322data DocNote = DocNote

330data DocNote = DocNote

323 { _noteTitle :: String

331 { _noteTitle :: String

324 , _noteBody :: [String]

332 , _noteBody :: [String]

325− } deriving (Eq, Show)

333+ } deriving (Eq, Ord, Show)

326

334

327-- | Type of extra information that a user may wish to "union" with their

335-- | Type of extra information that a user may wish to "union" with their

328-- documentation.

336-- documentation.

@@ -341,7 +349,7 @@ instance Monoid (ExtraInfo a) where

341-- - List corresponds to @QueryParams@, i.e GET parameters with multiple values

349-- - List corresponds to @QueryParams@, i.e GET parameters with multiple values

342-- - Flag corresponds to @QueryFlag@, i.e a value-less GET parameter

350-- - Flag corresponds to @QueryFlag@, i.e a value-less GET parameter

343data ParamKind = Normal | List | Flag

351data ParamKind = Normal | List | Flag

344− deriving (Eq, Show)

352+ deriving (Eq, Ord, Show)

345

353

346-- | A type to represent an HTTP response. Has an 'Int' status, a list of

354-- | A type to represent an HTTP response. Has an 'Int' status, a list of

347-- possible 'MediaType's, and a list of example 'ByteString' response bodies.

355-- possible 'MediaType's, and a list of example 'ByteString' response bodies.

@@ -362,7 +370,7 @@ data Response = Response

362 { _respStatus :: Int

370 { _respStatus :: Int

363 , _respTypes :: [M.MediaType]

371 , _respTypes :: [M.MediaType]

364 , _respBody :: [(Text, M.MediaType, ByteString)]

372 , _respBody :: [(Text, M.MediaType, ByteString)]

365− } deriving (Eq, Show)

373+ } deriving (Eq, Ord, Show)

366

374

367-- | Default response: status code 200, no response body.

375-- | Default response: status code 200, no response body.

368--

376--

@@ -394,7 +402,7 @@ data Action = Action

394 , _rqtypes :: [M.MediaType] -- type collected

402 , _rqtypes :: [M.MediaType] -- type collected

395 , _rqbody :: [(M.MediaType, ByteString)] -- user supplied

403 , _rqbody :: [(M.MediaType, ByteString)] -- user supplied

396 , _response :: Response -- user supplied

404 , _response :: Response -- user supplied

397− } deriving (Eq, Show)

405+ } deriving (Eq, Ord, Show)

398

406

399-- | Combine two Actions, we can't make a monoid as merging Response breaks the

407-- | Combine two Actions, we can't make a monoid as merging Response breaks the

400-- laws.

408-- laws.

@@ -611,7 +619,7 @@ class ToCapture c where

611markdown :: API -> String

619markdown :: API -> String

612markdown api = unlines $

620markdown api = unlines $

613 introsStr (api ^. apiIntros)

621 introsStr (api ^. apiIntros)

614− ++ (concatMap (uncurry printEndpoint) . HM.toList $ api ^. apiEndpoints)

622+ ++ (concatMap (uncurry printEndpoint) . sort . HM.toList $ api ^. apiEndpoints)

615

623

616 where printEndpoint :: Endpoint -> Action -> [String]

624 where printEndpoint :: Endpoint -> Action -> [String]

617 printEndpoint endpoint action =

625 printEndpoint endpoint action =