Document the search endpoint and query string

src/Lib.hs

@@ -23,17 +23,21 @@ import Network.Wai
 import Network.Wai.Handler.Warp
 import Network.Wai.Logger
 import Servant
-  ( Get,
+  ( Description,
+    Get,
+    Handler,
     JSON,
     Proxy (..),
+    QueryParam',
     Raw,
     Server,
+    Summary,
     serve,
     serveDirectoryFileServer,
     type (:<|>) (..),
     type (:>),
   )
-import Servant.OpenApi
+import Servant.OpenApi (HasOpenApi (toOpenApi))
 
 data Prices = Prices
   { usd :: Maybe Text,
@@ -68,7 +72,113 @@ instance ToJSON Card
 
 instance ToSchema Card
 
-type SearchCards = "search" :> Get '[JSON] [Card]
+type SearchCards =
+  Summary "Search for cards in a collection."
+    :> Description
+         "Text in the query string will be used to filter cards having that text in their \n\
+         \name. Additionally, the keyword expressions below can be used to search for \n\
+         \cards with certain properties. \n\
+         \ \n\
+         \ \n\
+         \### Examples \n\
+         \ \n\
+         \`bolt` \n\
+         \: Find all cards with \"bolt\" in the name \n\
+         \ \n\
+         \`\"God of\"` \n\
+         \: Find all cards with \"God of\" in the name \n\
+         \ \n\
+         \`t:legendary t:creature c:jund` \n\
+         \: Find all legendary creatures with a color \n\
+         \    identity of red/blue/green \n\
+         \ \n\
+         \`color<=ubg` \n\
+         \: Find all spells that are blue, black, green, or any \n\
+         \    combination thereof. \n\
+         \ \n\
+         \`color:red set:stx rarity>=rare` \n\
+         \: Find all red cards in Strixhaven that are \n\
+         \    rare or mythic \n\
+         \ \n\
+         \`t:enchantment o:\"enters the battlefield\"` \n\
+         \: Find all enchantments with ETB \n\
+         \    effects \n\
+         \ \n\
+         \ \n\
+         \### Keywords \n\
+         \ \n\
+         \ \n\
+         \#### Colors \n\
+         \ \n\
+         \Keywords \n\
+         \: `c`, `color` \n\
+         \ \n\
+         \Operators \n\
+         \: `:` (matches), `>=` (greater than or equal to), `<=` (less than \n\
+         \    or equal to) \n\
+         \ \n\
+         \Matches cards of the chosen color or colors. \n\
+         \ \n\
+         \Single colors \n\
+         \: `w` or `white`, `u` or `blue`, `b` or `black, =g` or `green`, `r` or `red` \n\
+         \ \n\
+         \Any combination of abbreviated single colors \n\
+         \: e.g.: `rg`, `uw`, or `wubgr` \n\
+         \ \n\
+         \Ravnican guilds \n\
+         \: `boros` (white/red), `golgari` (green/black), `selesnya` \n\
+         \    (green/white), `dimir` (blue/black), `orzhov` (white/black), `izzet` \n\
+         \    (blue/red), `gruul` (red/green), `azorius` (white/blue), `rakdos` (black/red), \n\
+         \    `simic` (green/blue) \n\
+         \ \n\
+         \Alaran shards \n\
+         \: `bant` (white/green/blue), `esper` (blue/white/black), \n\
+         \    `grixis` (black/blue/red), `jund` (red/blue/green), `naya` (green/red/white) \n\
+         \ \n\
+         \Tarkirian wedges \n\
+         \: `abzan` (white/black/green), `jeskai` (white/blue/red), \n\
+         \    `sultai` (blue/black/green), `mardu` (white/black/red), `temur` \n\
+         \    (blue/red/green) \n\
+         \ \n\
+         \ \n\
+         \#### Sets \n\
+         \ \n\
+         \Keywords \n\
+         \: `s`, `set`, `e`, `expansion` \n\
+         \ \n\
+         \Operators \n\
+         \: `:` (matches) \n\
+         \ \n\
+         \ \n\
+         \#### Rarity \n\
+         \ \n\
+         \Keywords \n\
+         \: `r`, `rarity` \n\
+         \ \n\
+         \Operators \n\
+         \: `:` (matches), `>=` (greater than or equal to), `<=` (less than \n\
+         \    or equal to) \n\
+         \ \n\
+         \ \n\
+         \#### Type \n\
+         \ \n\
+         \Keywords \n\
+         \: `t`, `type` \n\
+         \ \n\
+         \Operators \n\
+         \: `:` (matches) \n\
+         \ \n\
+         \ \n\
+         \#### Oracle Text \n\
+         \ \n\
+         \Keywords \n\
+         \: `o`, `oracle` \n\
+         \ \n\
+         \Operators \n\
+         \: `:` (matches)"
+    :> "search"
+    :> QueryParam' '[Description "Query string"] "q" Text
+    :> Get '[JSON] [Card]
 
 type TutorAPI =
   SearchCards
@@ -100,10 +210,9 @@ openapi =
     & info . version .~ "1.0"
     & info . description ?~ "An API for searching a Magic: The Gathering card collection."
     & info . license ?~ ("MIT" & url ?~ URL "http://mit.com")
-    & applyTagsFor (subOperations (Proxy :: Proxy SearchCards) tutorAPI) ["Search" & description ?~ "Searching Cards"]
 
 tutorServer :: Server TutorAPI
-tutorServer = return cards
+tutorServer = cards
 
 docsServer :: Server DocsAPI
 docsServer = return openapi
@@ -114,8 +223,8 @@ elmServer = serveDirectoryFileServer "www/public"
 server :: Server API
 server = tutorServer :<|> docsServer :<|> elmServer
 
-cards :: [Card]
-cards =
+cards :: Maybe Text -> Handler [Card]
+cards q = return
   [ Card
       { scryfall_id = fromJust $ fromText "f6cd7465-9dd0-473c-ac5e-dd9e2f22f5f6",
         name = "Esika, God of the Tree // The Prismatic Bridge",