Add OpenAPI documentation

package.yaml

@@ -21,6 +21,8 @@ description:         Please see the README on GitHub at <https://github.com/gith
 dependencies:
 - base >= 4.7 && < 5
 - aeson
+- openapi3
+- servant-openapi3
 - servant-server
 - text
 - uuid

src/Lib.hs

@@ -1,4 +1,6 @@
 {-# LANGUAGE DataKinds #-}
+{-# LANGUAGE DeriveDataTypeable #-}
+{-# LANGUAGE DeriveGeneric #-}
 {-# LANGUAGE OverloadedStrings #-}
 {-# LANGUAGE TemplateHaskell #-}
 {-# LANGUAGE TypeOperators #-}
@@ -12,8 +14,11 @@ where
 import Data.Aeson
 import Data.Aeson.TH
 import Data.Maybe
+import Data.OpenApi hiding (Server, name, server)
 import Data.Text
+import Data.Typeable (Typeable)
 import Data.UUID
+import GHC.Generics
 import Network.Wai
 import Network.Wai.Handler.Warp
 import Network.Wai.Logger
@@ -28,6 +33,7 @@ import Servant
     type (:<|>) (..),
     type (:>),
   )
+import Servant.OpenApi
 
 data Prices = Prices
   { usd :: Maybe Text,
@@ -36,10 +42,12 @@ data Prices = Prices
     eur_foil :: Maybe Text,
     tix :: Maybe Text
   }
-  deriving (Eq, Show)
+  deriving (Eq, Show, Generic, Typeable)
 
 $(deriveJSON defaultOptions ''Prices)
 
+instance ToSchema Prices
+
 data Card = Card
   { scryfall_id :: UUID,
     name :: Text,
@@ -50,13 +58,21 @@ data Card = Card
     oracle_text :: Maybe Text,
     prices :: Prices
   }
-  deriving (Eq, Show)
+  deriving (Eq, Show, Generic, Typeable)
 
 $(deriveJSON defaultOptions ''Card)
 
-type API =
+instance ToSchema Card
+
+type TutorAPI =
   "search" :> Get '[JSON] [Card]
-    :<|> Raw
+
+type DocsAPI =
+  "api" :> "openapi.json" :> Get '[JSON] OpenApi
+
+type ElmAPI = Raw
+
+type API = TutorAPI :<|> DocsAPI :<|> ElmAPI
 
 startApp :: IO ()
 startApp = withStdoutLogger $ \logger ->
@@ -65,13 +81,26 @@ startApp = withStdoutLogger $ \logger ->
 app :: Application
 app = serve api server
 
+tutorAPI :: Proxy TutorAPI
+tutorAPI = Proxy
+
 api :: Proxy API
 api = Proxy
 
+openapi :: OpenApi
+openapi = toOpenApi tutorAPI
+
+tutorServer :: Server TutorAPI
+tutorServer = return cards
+
+docsServer :: Server DocsAPI
+docsServer = return openapi
+
+elmServer :: Server ElmAPI
+elmServer = serveDirectoryFileServer "www/public"
+
 server :: Server API
-server =
-  return cards
-    :<|> serveDirectoryFileServer "www/public"
+server = tutorServer :<|> docsServer :<|> elmServer
 
 cards :: [Card]
 cards =

stack.yaml

@@ -17,8 +17,7 @@
 #
 # resolver: ./custom-snapshot.yaml
 # resolver: https://example.com/snapshots/2018-01-01.yaml
-resolver:
-  url: https://raw.githubusercontent.com/commercialhaskell/stackage-snapshots/master/lts/18/28.yaml
+resolver: lts-19.0
 
 # User packages to be built.
 # Various formats can be used as shown in the example below.
@@ -40,7 +39,9 @@ packages:
 # - git: https://github.com/commercialhaskell/stack.git
 #   commit: e7b331f14bcffb8367cd58fbfc8b40ec7642100a
 #
-# extra-deps: []
+extra-deps:
+  - hspec-wai-0.11.0@sha256:79f8aab21161cd551e0bb740f5416fb622fe94f710bedc97dabd39fe901b5291,2314
+  - hspec-wai-json-0.11.0@sha256:1fdd66a61c84a9ba6f2e1673ed49b2da1f57f025cd3fb9a46d62620ff9259d63,1629
 
 # Override default flag values for local packages and extra-deps
 # flags: {}

stack.yaml.lock

@@ -3,11 +3,24 @@
 # For more information, please see the documentation at:
 #   https://docs.haskellstack.org/en/stable/lock_files
 
-packages: []
+packages:
+- completed:
+    hackage: hspec-wai-0.11.0@sha256:79f8aab21161cd551e0bb740f5416fb622fe94f710bedc97dabd39fe901b5291,2314
+    pantry-tree:
+      size: 809
+      sha256: 7a3bceb28c15079f039a3d5c0b639f887ae881c27359b43f46145db3845c4795
+  original:
+    hackage: hspec-wai-0.11.0@sha256:79f8aab21161cd551e0bb740f5416fb622fe94f710bedc97dabd39fe901b5291,2314
+- completed:
+    hackage: hspec-wai-json-0.11.0@sha256:1fdd66a61c84a9ba6f2e1673ed49b2da1f57f025cd3fb9a46d62620ff9259d63,1629
+    pantry-tree:
+      size: 349
+      sha256: c25b93d8e0140a9ea24605199de5065967cd5fceeacac2b7f7d0747ab2142778
+  original:
+    hackage: hspec-wai-json-0.11.0@sha256:1fdd66a61c84a9ba6f2e1673ed49b2da1f57f025cd3fb9a46d62620ff9259d63,1629
 snapshots:
 - completed:
-    size: 590100
-    url: https://raw.githubusercontent.com/commercialhaskell/stackage-snapshots/master/lts/18/28.yaml
-    sha256: 428ec8d5ce932190d3cbe266b9eb3c175cd81e984babf876b64019e2cbe4ea68
-  original:
-    url: https://raw.githubusercontent.com/commercialhaskell/stackage-snapshots/master/lts/18/28.yaml
+    size: 616897
+    url: https://raw.githubusercontent.com/commercialhaskell/stackage-snapshots/master/lts/19/0.yaml
+    sha256: bbf2be02f17940bac1f87cb462d4fb0c3355de6dcfc53d84f4f9ad3ee2164f65
+  original: lts-19.0

tutor.cabal

@@ -31,6 +31,8 @@ library
   build-depends:
       aeson
     , base >=4.7 && <5
+    , openapi3
+    , servant-openapi3
     , servant-server
     , text
     , uuid
@@ -49,6 +51,8 @@ executable tutor-exe
   build-depends:
       aeson
     , base
+    , openapi3
+    , servant-openapi3
     , servant-server
     , text
     , tutor
@@ -72,6 +76,8 @@ test-suite tutor-test
     , hspec
     , hspec-wai
     , hspec-wai-json
+    , openapi3
+    , servant-openapi3
     , servant-server
     , text
     , tutor

www/public/api/index.html

@@ -0,0 +1,24 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Redoc</title>
+    <!-- needed for adaptive design -->
+    <meta charset="utf-8"/>
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
+
+    <!--
+    Redoc doesn't change outer page styles
+    -->
+    <style>
+      body {
+        margin: 0;
+        padding: 0;
+      }
+    </style>
+  </head>
+  <body>
+    <redoc spec-url='/api/openapi.json'></redoc>
+    <script src="https://cdn.jsdelivr.net/npm/redoc@latest/bundles/redoc.standalone.js"> </script>
+  </body>
+</html>