@@ -9,9 +9,25 @@ import Servant.Docs
9import Servant.Server
9import Servant.Server
11-- | Union of two APIs, first takes precedence in case of overlap.
11-- | Union of two APIs, first takes precedence in case of overlap.
15+-- > type MyApi = "books" :> Get [Book] -- GET /books
16+-- > :<|> "books" :> ReqBody Book :> Post Book -- POST /books
12data a :<|> b = a :<|> b
17data a :<|> b = a :<|> b
13infixr 8 :<|>
18infixr 8 :<|>
20+-- | A server for @a ':<|>' b@ first tries to match the request again the route
21+-- represented by @a@ and if it fails tries @b@. You must provide a request
22+-- handler for each route.
24+-- > type MyApi = "books" :> Get [Book] -- GET /books
25+-- > :<|> "books" :> ReqBody Book :> Post Book -- POST /books
27+-- > server :: Server MyApi
28+-- > server = listAllBooks :<|> postBook
29+-- > where listAllBooks = ...
30+-- > postBook book = ...
15instance (HasServer a, HasServer b) => HasServer (a :<|> b) where
31instance (HasServer a, HasServer b) => HasServer (a :<|> b) where
16 type Server (a :<|> b) = Server a :<|> Server b
32 type Server (a :<|> b) = Server a :<|> Server b
17 route Proxy (a :<|> b) request respond =
33 route Proxy (a :<|> b) request respond =
@@ -23,12 +39,27 @@ instance (HasServer a, HasServer b) => HasServer (a :<|> b) where
23 where pa = Proxy :: Proxy a
39 where pa = Proxy :: Proxy a
24 pb = Proxy :: Proxy b
40 pb = Proxy :: Proxy b
42+-- | A client querying function for @a ':<|>' b@ will actually hand you
43+-- one function for querying @a@ and another one for querying @b@,
44+-- stitching them together with ':<|>', which really is just like a pair.
46+-- > type MyApi = "books" :> Get [Book] -- GET /books
47+-- > :<|> "books" :> ReqBody Book :> Post Book -- POST /books
49+-- > myApi :: Proxy MyApi
52+-- > getAllBooks :: BaseUrl -> EitherT String IO [Book]
53+-- > postNewBook :: Book -> BaseUrl -> EitherT String IO Book
54+-- > (getAllBooks :<|> postNewBook) = client myApi
26instance (HasClient a, HasClient b) => HasClient (a :<|> b) where
55instance (HasClient a, HasClient b) => HasClient (a :<|> b) where
27 type Client (a :<|> b) = Client a :<|> Client b
56 type Client (a :<|> b) = Client a :<|> Client b
28 clientWithRoute Proxy req =
57 clientWithRoute Proxy req =
29 clientWithRoute (Proxy :: Proxy a) req :<|>
58 clientWithRoute (Proxy :: Proxy a) req :<|>
30 clientWithRoute (Proxy :: Proxy b) req
59 clientWithRoute (Proxy :: Proxy b) req
61+-- | The generated docs for @a ':<|>' b@ just append the docs
62+-- for @a@ with the docs for @b@.
32instance (HasDocs layout1, HasDocs layout2)
63instance (HasDocs layout1, HasDocs layout2)
33 => HasDocs (layout1 :<|> layout2) where
64 => HasDocs (layout1 :<|> layout2) where