-- |
-- Module:      Servant.OpenApi
-- License:     BSD3
-- Maintainer:  Nickolay Kudasov <nickolay@getshoptv.com>
-- Stability:   experimental
--
-- This module provides means to generate and manipulate
-- OpenApi specification for servant APIs.
--
-- OpenApi is a project used to describe and document RESTful APIs.
--
-- The OpenApi specification defines a set of files required to describe such an API.
-- These files can then be used by the OpenApi-UI project to display the API
-- and OpenApi-Codegen to generate clients in various languages.
-- Additional utilities can also take advantage of the resulting files, such as testing tools.
--
-- For more information see <http://swagger.io/ OpenApi documentation>.
module Servant.OpenApi (
  -- * How to use this library
  -- $howto

  -- ** Generate @'OpenApi'@
  -- $generate

  -- ** Annotate
  -- $annotate

  -- ** Test
  -- $test

  -- ** Serve
  -- $serve

  -- * @'HasOpenApi'@ class
  HasOpenApi(..),

  -- * Manipulation
  subOperations,

  -- * Testing
  validateEveryToJSON,
  validateEveryToJSONWithPatternChecker,
) where

import           Servant.OpenApi.Internal
import           Servant.OpenApi.Test
import           Servant.OpenApi.Internal.Orphans ()

-- $setup
-- >>> import Control.Applicative
-- >>> import Control.Lens
-- >>> import Data.Aeson
-- >>> import Data.OpenApi
-- >>> import Data.Typeable
-- >>> import GHC.Generics
-- >>> import Servant.API
-- >>> import Test.Hspec
-- >>> import Test.QuickCheck
-- >>> import qualified Data.ByteString.Lazy.Char8 as BSL8
-- >>> import Servant.OpenApi.Internal.Test
-- >>> :set -XDataKinds
-- >>> :set -XDeriveDataTypeable
-- >>> :set -XDeriveGeneric
-- >>> :set -XGeneralizedNewtypeDeriving
-- >>> :set -XOverloadedStrings
-- >>> :set -XTypeOperators
-- >>> data User = User { name :: String, age :: Int } deriving (Show, Generic, Typeable)
-- >>> newtype UserId = UserId Integer deriving (Show, Generic, Typeable, ToJSON)
-- >>> instance ToJSON User
-- >>> instance ToSchema User
-- >>> instance ToSchema UserId
-- >>> instance ToParamSchema UserId
-- >>> type GetUsers = Get '[JSON] [User]
-- >>> type GetUser  = Capture "user_id" UserId :> Get '[JSON] User
-- >>> type PostUser = ReqBody '[JSON] User :> Post '[JSON] UserId
-- >>> type UserAPI  = GetUsers :<|> GetUser :<|> PostUser

-- $howto
--
-- This section explains how to use this library to generate OpenApi specification,
-- modify it and run automatic tests for a servant API.
--
-- For the purposes of this section we will use this servant API:
--
-- >>> data User = User { name :: String, age :: Int } deriving (Show, Generic, Typeable)
-- >>> newtype UserId = UserId Integer deriving (Show, Generic, Typeable, ToJSON)
-- >>> instance ToJSON User
-- >>> instance ToSchema User
-- >>> instance ToSchema UserId
-- >>> instance ToParamSchema UserId
-- >>> type GetUsers = Get '[JSON] [User]
-- >>> type GetUser  = Capture "user_id" UserId :> Get '[JSON] User
-- >>> type PostUser = ReqBody '[JSON] User :> Post '[JSON] UserId
-- >>> type UserAPI  = GetUsers :<|> GetUser :<|> PostUser
--
-- Here we define a user API with three endpoints. @GetUsers@ endpoint returns a list of all users.
-- @GetUser@ returns a user given his\/her ID. @PostUser@ creates a new user and returns his\/her ID.

-- $generate
-- In order to generate @'OpenApi'@ specification for a servant API, just use @'toOpenApi'@:
--
-- >>> BSL8.putStrLn $ encodePretty $ toOpenApi (Proxy :: Proxy UserAPI)
-- {
--     "components": {
--         "schemas": {
--             "User": {
--                 "properties": {
--                     "age": {
--                         "maximum": 9223372036854775807,
--                         "minimum": -9223372036854775808,
--                         "type": "integer"
--                     },
--                     "name": {
--                         "type": "string"
--                     }
--                 },
--                 "required": [
--                     "name",
--                     "age"
--                 ],
--                 "type": "object"
--             },
--             "UserId": {
--                 "type": "integer"
--             }
--         }
--     },
--     "info": {
--         "title": "",
--         "version": ""
--     },
--     "openapi": "3.0.0",
--     "paths": {
--         "/": {
--             "get": {
--                 "responses": {
--                     "200": {
--                         "content": {
--                             "application/json;charset=utf-8": {
--                                 "schema": {
--                                     "items": {
--                                         "$ref": "#/components/schemas/User"
--                                     },
--                                     "type": "array"
--                                 }
--                             }
--                         },
--                         "description": ""
--                     }
--                 }
--             },
--             "post": {
--                 "requestBody": {
--                     "content": {
--                         "application/json;charset=utf-8": {
--                             "schema": {
--                                 "$ref": "#/components/schemas/User"
--                             }
--                         }
--                     }
--                 },
--                 "responses": {
--                     "200": {
--                         "content": {
--                             "application/json;charset=utf-8": {
--                                 "schema": {
--                                     "$ref": "#/components/schemas/UserId"
--                                 }
--                             }
--                         },
--                         "description": ""
--                     },
--                     "400": {
--                         "description": "Invalid `body`"
--                     }
--                 }
--             }
--         },
--         "/{user_id}": {
--             "get": {
--                 "parameters": [
--                     {
--                         "in": "path",
--                         "name": "user_id",
--                         "required": true,
--                         "schema": {
--                             "type": "integer"
--                         }
--                     }
--                 ],
--                 "responses": {
--                     "200": {
--                         "content": {
--                             "application/json;charset=utf-8": {
--                                 "schema": {
--                                     "$ref": "#/components/schemas/User"
--                                 }
--                             }
--                         },
--                         "description": ""
--                     },
--                     "404": {
--                         "description": "`user_id` not found"
--                     }
--                 }
--             }
--         }
--     }
-- }
--
-- By default @'toOpenApi'@ will generate specification for all API routes, parameters, headers, responses and data schemas.
--
-- For some parameters it will also add 400 and/or 404 responses with a description mentioning parameter name.
--
-- Data schemas come from @'ToParamSchema'@ and @'ToSchema'@ classes.

-- $annotate
-- While initially generated @'OpenApi'@ looks good, it lacks some information it can't get from a servant API.
--
-- We can add this information using field lenses from @"Data.OpenApi"@:
--
-- >>> :{
-- BSL8.putStrLn $ encodePretty $ toOpenApi (Proxy :: Proxy UserAPI)
--   & info.title        .~ "User API"
--   & info.version      .~ "1.0"
--   & info.description  ?~ "This is an API for the Users service"
--   & info.license      ?~ "MIT"
--   & servers           .~ ["https://example.com"]
-- :}
-- {
--     "components": {
--         "schemas": {
--             "User": {
--                 "properties": {
--                     "age": {
--                         "maximum": 9223372036854775807,
--                         "minimum": -9223372036854775808,
--                         "type": "integer"
--                     },
--                     "name": {
--                         "type": "string"
--                     }
--                 },
--                 "required": [
--                     "name",
--                     "age"
--                 ],
--                 "type": "object"
--             },
--             "UserId": {
--                 "type": "integer"
--             }
--         }
--     },
--     "info": {
--         "description": "This is an API for the Users service",
--         "license": {
--             "name": "MIT"
--         },
--         "title": "User API",
--         "version": "1.0"
--     },
--     "openapi": "3.0.0",
--     "paths": {
--         "/": {
--             "get": {
--                 "responses": {
--                     "200": {
--                         "content": {
--                             "application/json;charset=utf-8": {
--                                 "schema": {
--                                     "items": {
--                                         "$ref": "#/components/schemas/User"
--                                     },
--                                     "type": "array"
--                                 }
--                             }
--                         },
--                         "description": ""
--                     }
--                 }
--             },
--             "post": {
--                 "requestBody": {
--                     "content": {
--                         "application/json;charset=utf-8": {
--                             "schema": {
--                                 "$ref": "#/components/schemas/User"
--                             }
--                         }
--                     }
--                 },
--                 "responses": {
--                     "200": {
--                         "content": {
--                             "application/json;charset=utf-8": {
--                                 "schema": {
--                                     "$ref": "#/components/schemas/UserId"
--                                 }
--                             }
--                         },
--                         "description": ""
--                     },
--                     "400": {
--                         "description": "Invalid `body`"
--                     }
--                 }
--             }
--         },
--         "/{user_id}": {
--             "get": {
--                 "parameters": [
--                     {
--                         "in": "path",
--                         "name": "user_id",
--                         "required": true,
--                         "schema": {
--                             "type": "integer"
--                         }
--                     }
--                 ],
--                 "responses": {
--                     "200": {
--                         "content": {
--                             "application/json;charset=utf-8": {
--                                 "schema": {
--                                     "$ref": "#/components/schemas/User"
--                                 }
--                             }
--                         },
--                         "description": ""
--                     },
--                     "404": {
--                         "description": "`user_id` not found"
--                     }
--                 }
--             }
--         }
--     },
--     "servers": [
--         {
--             "url": "https://example.com"
--         }
--     ]
-- }
--
-- It is also useful to annotate or modify certain endpoints.
-- @'subOperations'@ provides a convenient way to zoom into a part of an API.
--
-- @'subOperations' sub api@ traverses all operations of the @api@ which are also present in @sub@.
-- Furthermore, @sub@ is required to be an exact sub API of @api. Otherwise it will not typecheck.
--
-- @"Data.OpenApi.Operation"@ provides some useful helpers that can be used with @'subOperations'@.
-- One example is applying tags to certain endpoints:
--
-- >>> let getOps  = subOperations (Proxy :: Proxy (GetUsers :<|> GetUser)) (Proxy :: Proxy UserAPI)
-- >>> let postOps = subOperations (Proxy :: Proxy PostUser) (Proxy :: Proxy UserAPI)
-- >>> :{
-- BSL8.putStrLn $ encodePretty $ toOpenApi (Proxy :: Proxy UserAPI)
--   & applyTagsFor getOps  ["get"  & description ?~ "GET operations"]
--   & applyTagsFor postOps ["post" & description ?~ "POST operations"]
-- :}
-- {
--     "components": {
--         "schemas": {
--             "User": {
--                 "properties": {
--                     "age": {
--                         "maximum": 9223372036854775807,
--                         "minimum": -9223372036854775808,
--                         "type": "integer"
--                     },
--                     "name": {
--                         "type": "string"
--                     }
--                 },
--                 "required": [
--                     "name",
--                     "age"
--                 ],
--                 "type": "object"
--             },
--             "UserId": {
--                 "type": "integer"
--             }
--         }
--     },
--     "info": {
--         "title": "",
--         "version": ""
--     },
--     "openapi": "3.0.0",
--     "paths": {
--         "/": {
--             "get": {
--                 "responses": {
--                     "200": {
--                         "content": {
--                             "application/json;charset=utf-8": {
--                                 "schema": {
--                                     "items": {
--                                         "$ref": "#/components/schemas/User"
--                                     },
--                                     "type": "array"
--                                 }
--                             }
--                         },
--                         "description": ""
--                     }
--                 },
--                 "tags": [
--                     "get"
--                 ]
--             },
--             "post": {
--                 "requestBody": {
--                     "content": {
--                         "application/json;charset=utf-8": {
--                             "schema": {
--                                 "$ref": "#/components/schemas/User"
--                             }
--                         }
--                     }
--                 },
--                 "responses": {
--                     "200": {
--                         "content": {
--                             "application/json;charset=utf-8": {
--                                 "schema": {
--                                     "$ref": "#/components/schemas/UserId"
--                                 }
--                             }
--                         },
--                         "description": ""
--                     },
--                     "400": {
--                         "description": "Invalid `body`"
--                     }
--                 },
--                 "tags": [
--                     "post"
--                 ]
--             }
--         },
--         "/{user_id}": {
--             "get": {
--                 "parameters": [
--                     {
--                         "in": "path",
--                         "name": "user_id",
--                         "required": true,
--                         "schema": {
--                             "type": "integer"
--                         }
--                     }
--                 ],
--                 "responses": {
--                     "200": {
--                         "content": {
--                             "application/json;charset=utf-8": {
--                                 "schema": {
--                                     "$ref": "#/components/schemas/User"
--                                 }
--                             }
--                         },
--                         "description": ""
--                     },
--                     "404": {
--                         "description": "`user_id` not found"
--                     }
--                 },
--                 "tags": [
--                     "get"
--                 ]
--             }
--         }
--     },
--     "tags": [
--         {
--             "description": "GET operations",
--             "name": "get"
--         },
--         {
--             "description": "POST operations",
--             "name": "post"
--         }
--     ]
-- }
--
-- This applies @\"get\"@ tag to the @GET@ endpoints and @\"post\"@ tag to the @POST@ endpoint of the User API.

-- $test
-- Automatic generation of data schemas uses @'ToSchema'@ instances for the types
-- used in a servant API. But to encode/decode actual data servant uses different classes.
-- For instance in @UserAPI@ @User@ is always encoded/decoded using @'ToJSON'@ and @'FromJSON'@ instances.
--
-- To be sure your Haskell server/client handles data properly you need to check
-- that @'ToJSON'@ instance always generates values that satisfy schema produced
-- by @'ToSchema'@ instance.
--
-- With @'validateEveryToJSON'@ it is possible to test all those instances automatically,
-- without having to write down every type:
--
-- >>> instance Arbitrary User where arbitrary = User <$> arbitrary <*> arbitrary
-- >>> instance Arbitrary UserId where arbitrary = UserId <$> arbitrary
-- >>> hspec $ validateEveryToJSON (Proxy :: Proxy UserAPI)
-- <BLANKLINE>
-- [User]...
-- ...
-- User...
-- ...
-- UserId...
-- ...
-- Finished in ... seconds
-- ...3 examples, 0 failures...
--
-- Although servant is great, chances are that your API clients don't use Haskell.
-- In many cases @swagger.json@ serves as a specification, not a Haskell type.
--
-- In this cases it is a good idea to store generated and annotated @'OpenApi'@ in a @swagger.json@ file
-- under a version control system (such as Git, Subversion, Mercurial, etc.).
--
-- It is also recommended to version API based on changes to the @swagger.json@ rather than changes
-- to the Haskell API.
--
-- See <example/test/TodoSpec.hs TodoSpec.hs> for an example of a complete test suite for a swagger specification.

-- $serve
-- If you're implementing a server for an API, you might also want to serve its @'OpenApi'@ specification.
--
-- See <example/src/Todo.hs Todo.hs> for an example of a server.