git.iko.soy/servant
on master help sign in
use Capture Description if available (#1423)
0cb2d60Samuel Gélineau
servant-docs/golden/comprehensive.md+2−2
compare with master
unifiedsplit
@@ -52,11 +52,11 @@
52
52
53```
53```
54
54
55−## GET /capture/:foo
55+## GET /capture/:bar
56
56
57### Captures:
57### Captures:
58
58
59−- *foo*: Capture foo Int
59+- *bar*: example description
60
60
61### Response:
61### Response:
62
62
servant-docs/src/Servant/Docs/Internal.hs+23−1
@@ -862,7 +862,7 @@ instance HasDocs EmptyAPI where
862-- | @"books" :> 'Capture' "isbn" Text@ will appear as
862-- | @"books" :> 'Capture' "isbn" Text@ will appear as
863-- @/books/:isbn@ in the docs.
863-- @/books/:isbn@ in the docs.
864instance (KnownSymbol sym, ToCapture (Capture sym a), HasDocs api)
864instance (KnownSymbol sym, ToCapture (Capture sym a), HasDocs api)
865− => HasDocs (Capture' mods sym a :> api) where
865+ => HasDocs (Capture' '[] sym a :> api) where
866
866
867 docsFor Proxy (endpoint, action) =
867 docsFor Proxy (endpoint, action) =
868 docsFor subApiP (endpoint', action')
868 docsFor subApiP (endpoint', action')
@@ -874,6 +874,28 @@ instance (KnownSymbol sym, ToCapture (Capture sym a), HasDocs api)
874 endpoint' = over path (\p -> p ++ [":" ++ symbolVal symP]) endpoint
874 endpoint' = over path (\p -> p ++ [":" ++ symbolVal symP]) endpoint
875 symP = Proxy :: Proxy sym
875 symP = Proxy :: Proxy sym
876
876
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+
877
899
878-- | @"books" :> 'CaptureAll' "isbn" Text@ will appear as
900-- | @"books" :> 'CaptureAll' "isbn" Text@ will appear as
879-- @/books/:isbn@ in the docs.
901-- @/books/:isbn@ in the docs.
servant/src/Servant/Test/ComprehensiveAPI.hs+1−1
@@ -48,7 +48,7 @@ comprehensiveAPIWithoutStreaming = Proxy
48type ComprehensiveAPIWithoutStreamingOrRaw' endpoint =
48type ComprehensiveAPIWithoutStreamingOrRaw' endpoint =
49 GET
49 GET
50 :<|> "get-int" :> Get '[JSON] Int
50 :<|> "get-int" :> Get '[JSON] Int
51− :<|> "capture" :> Capture' '[Description "example description"] "foo" Int :> GET
51+ :<|> "capture" :> Capture' '[Description "example description"] "bar" Int :> GET
52 :<|> "capture-lenient" :> Capture' '[Lenient] "foo" Int :> GET
52 :<|> "capture-lenient" :> Capture' '[Lenient] "foo" Int :> GET
53 :<|> "header" :> Header "foo" Int :> GET
53 :<|> "header" :> Header "foo" Int :> GET
54 :<|> "header-lenient" :> Header' '[Required, Lenient] "bar" Int :> GET
54 :<|> "header-lenient" :> Header' '[Required, Lenient] "bar" Int :> GET