provide help on the leaderboard and OpenAPI specification

1 files changed, 68 insertions, 6 deletions

diff --git a/lambda-calcul/haskell/src/Minilang/API.hs b/lambda-calcul/haskell/src/Minilang/API.hs
index 94976d2..43baddf 100644
--- a/lambda-calcul/haskell/src/Minilang/API.hs
+++ b/lambda-calcul/haskell/src/Minilang/API.hs
@@ -13,11 +13,13 @@ import Data.Aeson (FromJSON, ToJSON)
 import Data.Bifunctor (first)
 import Data.ByteString.Lazy (ByteString)
 import qualified Data.ByteString.Lazy as LBS
+import Data.Data (Proxy (..))
 import Data.Text (Text)
 import Data.Time (UTCTime)
 import GHC.Generics (Generic)
 import Servant
   ( Delete,
+    Description,
     FromHttpApiData,
     Get,
     JSON,
@@ -26,6 +28,7 @@ import Servant
     Raw,
     ReqBody,
     StdMethod (POST),
+    Summary,
     ToHttpApiData,
     Verb,
     parseUrlPiece,
@@ -36,14 +39,73 @@ import Servant
 import System.Random (StdGen, uniformList)
 
 type LambdaAPI =
-  "api" :> "register" :> ReqBody '[JSON] User :> Verb 'POST 201 '[JSON] Token
-    :<|> "api" :> "register" :> QueryParam "token" Token :> Delete '[JSON] Score
-    :<|> "api" :> "leaderboard" :> Get '[JSON] [Score]
-    :<|> "api" :> "score" :> QueryParam "token" Token :> Get '[JSON] Score
-    :<|> "api" :> "challenge" :> QueryParam "token" Token :> Get '[JSON] Challenge
-    :<|> "api" :> "challenge" :> QueryParam "token" Token :> ReqBody '[JSON] Text :> Post '[JSON] ()
+  RegisterUser
+    :<|> UnregisterUser
+    :<|> GetLeaderboard
+    :<|> GetScoreFor
+    :<|> GetNextChallenge
+    :<|> PostAnswer
     :<|> Raw
 
+type RegisterUser =
+  Summary
+    "Register given username to participate in the contest and return a token if successful."
+    :> Description "Registration fails if the username is already registered"
+    :> "api"
+    :> "register"
+    :> ReqBody '[JSON] User
+    :> Verb 'POST 201 '[JSON] Token
+
+type UnregisterUser =
+  Summary "Unregister user for given token."
+    :> "api"
+    :> "register"
+    :> QueryParam "token" Token
+    :> Delete '[JSON] Score
+
+type GetLeaderboard =
+  Summary "Retrieve the current leaderboard as a list of scores for registered players"
+    :> "api"
+    :> "leaderboard"
+    :> Get '[JSON] [Score]
+
+type GetScoreFor =
+  Summary "Retrieve current score for user registered with given token"
+    :> "api"
+    :> "score"
+    :> QueryParam "token" Token
+    :> Get '[JSON] Score
+
+type GetNextChallenge =
+  Summary
+    "Retrieve the next challenge for user registered with given token."
+    :> Description
+         "The challenge is given as a string representing a λ-calculus expression\
+         \as expected by this implementation. Check the grammar presented in the /repl.html \
+         \page for more details\
+         \"
+    :> "api"
+    :> "challenge"
+    :> QueryParam "token" Token
+    :> Get '[JSON] Challenge
+
+type PostAnswer =
+  Summary
+    "Post an answer to the current challenge for the given user." :>
+    Description "The answer should be given as JSON string representing the result \
+    \of evaluating the current challenge's expression in the untyped λ-calculus. This \
+    \textual representation should be consistent with the grammar given in the REPL's \
+    \\"Help\" panel. Expect to be surprised 🤔 !\
+    \"
+    :> "api"
+    :> "challenge"
+    :> QueryParam "token" Token
+    :> ReqBody '[JSON] Text
+    :> Post '[JSON] ()
+
+lambdaAPI :: Proxy LambdaAPI
+lambdaAPI = Proxy
+
 data Score = Score
   { user :: User,
     grade :: Int,