git.iko.soy/typeable/servant
on master help sign in
use Capture Description if available (#1423)

* use Capture Description if available * update golden/comprehensive.md This is technically a breaking change, because if a Capture has both a Description and a ToCapture instance, the Description now takes precedence. Since this Description wasn't doing anything before, I am guessing that most projects currently only use Description to describe their endpoints and not their Captures, and thus that few people will be affected by this breaking change. * test the "no ToCapture instance" case The case in which there is both a Description and a ToCapture instance seems like a corner case. The more interesting cases are the one in which there is a Description but no ToCapture instance, and the case in which there is a ToCapture instance but no description.

commit0cb2d603c4cb1b1fc80af60b0aeb6e07c699a1d9 authorSamuel Gélineau <gelisam@simspace.com> dateTue 8 Jun 2021, 14:28 (5 years ago) parentda8e64b
3 files changed+26−4
compare with master
unifiedsplit
servant-docs/golden/comprehensive.md+2−2 servant-docs/src/Servant/Docs/Internal.hs+23−1 servant/src/Servant/Test/ComprehensiveAPI.hs+1−1
servant-docs/golden/comprehensive.md+2−2
@@ -52,11 +52,11 @@
5252
5353```
5454
55−## GET /capture/:foo
55+## GET /capture/:bar
5656
5757### Captures:
5858
59−- *foo*: Capture foo Int
59+- *bar*: example description
6060
6161### Response:
6262
servant-docs/src/Servant/Docs/Internal.hs+23−1
@@ -862,7 +862,7 @@ instance HasDocs EmptyAPI where
862862-- | @"books" :> 'Capture' "isbn" Text@ will appear as
863863-- @/books/:isbn@ in the docs.
864864instance (KnownSymbol sym, ToCapture (Capture sym a), HasDocs api)
865− => HasDocs (Capture' mods sym a :> api) where
865+ => HasDocs (Capture' '[] sym a :> api) where
866866
867867 docsFor Proxy (endpoint, action) =
868868 docsFor subApiP (endpoint', action')
@@ -874,6 +874,28 @@ instance (KnownSymbol sym, ToCapture (Capture sym a), HasDocs api)
874874 endpoint' = over path (\p -> p ++ [":" ++ symbolVal symP]) endpoint
875875 symP = Proxy :: Proxy sym
876876
877+instance (KnownSymbol descr, KnownSymbol sym, HasDocs api)
878+ => HasDocs (Capture' (Description descr ': mods) sym a :> api) where
879+
880+ docsFor Proxy (endpoint, action) =
881+ docsFor subApiP (endpoint', action')
882+
883+ where subApiP = Proxy :: Proxy api
884+
885+ docCapture = DocCapture (symbolVal symP) (symbolVal descrP)
886+ action' = over captures (|> docCapture) action
887+ endpoint' = over path (\p -> p ++ [":" ++ symbolVal symP]) endpoint
888+ descrP = Proxy :: Proxy descr
889+ symP = Proxy :: Proxy sym
890+
891+instance {-# OVERLAPPABLE #-} HasDocs (Capture' mods sym a :> api)
892+ => HasDocs (Capture' (mod ': mods) sym a :> api) where
893+
894+ docsFor Proxy =
895+ docsFor apiP
896+
897+ where apiP = Proxy :: Proxy (Capture' mods sym a :> api)
898+
877899
878900-- | @"books" :> 'CaptureAll' "isbn" Text@ will appear as
879901-- @/books/:isbn@ in the docs.
servant/src/Servant/Test/ComprehensiveAPI.hs+1−1
@@ -48,7 +48,7 @@ comprehensiveAPIWithoutStreaming = Proxy
4848type ComprehensiveAPIWithoutStreamingOrRaw' endpoint =
4949 GET
5050 :<|> "get-int" :> Get '[JSON] Int
51− :<|> "capture" :> Capture' '[Description "example description"] "foo" Int :> GET
51+ :<|> "capture" :> Capture' '[Description "example description"] "bar" Int :> GET
5252 :<|> "capture-lenient" :> Capture' '[Lenient] "foo" Int :> GET
5353 :<|> "header" :> Header "foo" Int :> GET
5454 :<|> "header-lenient" :> Header' '[Required, Lenient] "bar" Int :> GET