From 2e59a82d012bf670b015e4ee69efe1e740060a15 Mon Sep 17 00:00:00 2001
From: Catherine Galkina <catherine@getshoptv.com>
Date: Thu, 8 Jun 2017 17:35:24 +0300
Subject: [PATCH] Add Description and Summary combinators

---
 servant/servant.cabal                         |  1 +
 servant/src/Servant/API.hs                    |  4 +++
 servant/src/Servant/API/Description.hs        | 32 +++++++++++++++++++
 .../API/Internal/Test/ComprehensiveAPI.hs     |  2 ++
 4 files changed, 39 insertions(+)
 create mode 100644 servant/src/Servant/API/Description.hs

diff --git a/servant/servant.cabal b/servant/servant.cabal
index 5efd1f12..7f25bdb9 100644
--- a/servant/servant.cabal
+++ b/servant/servant.cabal
@@ -38,6 +38,7 @@ library
     Servant.API.BasicAuth
     Servant.API.Capture
     Servant.API.ContentTypes
+    Servant.API.Description
     Servant.API.Empty
     Servant.API.Experimental.Auth
     Servant.API.Header
diff --git a/servant/src/Servant/API.hs b/servant/src/Servant/API.hs
index f1a0e64b..88e4d934 100644
--- a/servant/src/Servant/API.hs
+++ b/servant/src/Servant/API.hs
@@ -34,6 +34,9 @@ module Servant.API (
   -- * Authentication
   module Servant.API.BasicAuth,
 
+  -- * Endpoints description
+  module Servant.API.Description,
+
   -- * Content Types
   module Servant.API.ContentTypes,
   -- | Serializing and deserializing types based on @Accept@ and
@@ -68,6 +71,7 @@ import           Servant.API.ContentTypes    (Accept (..), FormUrlEncoded,
                                               MimeRender (..), NoContent (NoContent),
                                               MimeUnrender (..), OctetStream,
                                               PlainText)
+import           Servant.API.Description     (Description, Summary)
 import           Servant.API.Empty           (EmptyAPI (..))
 import           Servant.API.Experimental.Auth (AuthProtect)
 import           Servant.API.Header          (Header (..))
diff --git a/servant/src/Servant/API/Description.hs b/servant/src/Servant/API/Description.hs
new file mode 100644
index 00000000..45dfb7fa
--- /dev/null
+++ b/servant/src/Servant/API/Description.hs
@@ -0,0 +1,32 @@
+{-# LANGUAGE DataKinds          #-}
+{-# LANGUAGE DeriveDataTypeable #-}
+{-# LANGUAGE PolyKinds          #-}
+{-# OPTIONS_HADDOCK not-home    #-}
+module Servant.API.Description (Description, Summary) where
+
+import           Data.Typeable (Typeable)
+import           GHC.TypeLits  (Symbol)
+-- | Add a short summary for (part of) API.
+--
+-- Example:
+--
+-- >>> type MyApi = Summary "Get book by ISBN." :> "books" :> Capture "isbn" Text :> Get '[JSON] Book
+data Summary (sym :: Symbol)
+    deriving (Typeable)
+
+-- | Add more verbose description for (part of) API.
+--
+-- Example:
+--
+-- >>> type MyApi = Description "Some longer implementation details here." :> "books" :> Capture "isbn" Text :> Get '[JSON] Book
+data Description (sym :: Symbol)
+    deriving (Typeable)
+
+-- $setup
+-- >>> import Servant.API
+-- >>> import Data.Aeson
+-- >>> import Data.Text
+-- >>> data Book
+-- >>> instance ToJSON Book where { toJSON = undefined }
+-- >>> data SourceFile
+-- >>> instance ToJSON SourceFile where { toJSON = undefined }
diff --git a/servant/src/Servant/API/Internal/Test/ComprehensiveAPI.hs b/servant/src/Servant/API/Internal/Test/ComprehensiveAPI.hs
index 0f39a910..cf3e1213 100644
--- a/servant/src/Servant/API/Internal/Test/ComprehensiveAPI.hs
+++ b/servant/src/Servant/API/Internal/Test/ComprehensiveAPI.hs
@@ -38,6 +38,8 @@ type ComprehensiveAPIWithoutRaw =
   Verb 'POST 204 '[JSON] Int :<|>
   WithNamedContext "foo" '[] GET :<|>
   CaptureAll "foo" Int :> GET :<|>
+  Summary "foo" :> GET :<|>
+  Description "foo" :> GET :<|>
   EmptyAPI
 
 comprehensiveAPIWithoutRaw :: Proxy ComprehensiveAPIWithoutRaw