servant-0.20.2: A family of combinators for defining webservices APIs

Safe Haskell | None
Language | Haskell2010

Servant.API.Description

Contents

- Combinators
- Used as modifiers

Synopsis

- data Description (sym :: Symbol)
- data Summary (sym :: Symbol)
- type FoldDescription (mods :: [Type]) = FoldDescription' "" mods
- type family FoldDescription' (acc :: Symbol) (mods :: [Type]) :: Symbol where ...
- reflectDescription :: forall (mods :: [Type]). KnownSymbol (FoldDescription mods) => Proxy mods -> String

# Combinators

data Description (sym :: Symbol) #

Add more verbose description for (part of) API.

Example:

    >>> :{
    type MyApi = Description
     "This comment is visible in multiple Servant interpretations \
     \and can be really long if necessary. \
     \Haskell multiline String support is not perfect \
     \but it's still very readable."
    :> Get '[JSON] Book
    :}

#### Instances

Instances details

HasLink sub => HasLink (Description s :> sub :: Type) # |
Instance details Defined in Servant.Links Methods toLink :: (Link -> a) -> Proxy (Description s :> sub) -> Link -> MkLink (Description s :> sub) a #
type MkLink (Description s :> sub :: Type) a # |
Instance details Defined in Servant.Links type MkLink (Description s :> sub :: Type) a = MkLink sub a

data Summary (sym :: Symbol) #

Add a short summary for (part of) API.

Example:

    >>> type MyApi = Summary "Get book by ISBN." :> "books" :> Capture "isbn" Text :> Get '[JSON] Book

#### Instances

Instances details

HasLink sub => HasLink (Summary s :> sub :: Type) # |
Instance details Defined in Servant.Links Methods toLink :: (Link -> a) -> Proxy (Summary s :> sub) -> Link -> MkLink (Summary s :> sub) a #
type MkLink (Summary s :> sub :: Type) a # |
Instance details Defined in Servant.Links type MkLink (Summary s :> sub :: Type) a = MkLink sub a

# Used as modifiers

type FoldDescription (mods :: [Type]) = FoldDescription' "" mods #

Fold list of modifiers to extract description as a type-level String.

    >>> :kind! FoldDescription '[]
    FoldDescription '[] :: Symbol
    = ""

    >>> :kind! FoldDescription '[Required, Description "foobar", Lenient]
    FoldDescription '[Required, Description "foobar", Lenient] :: Symbol
    = "foobar"

type family FoldDescription' (acc :: Symbol) (mods :: [Type]) :: Symbol where ... #

Implementation of `FoldDescription`.

Equations

FoldDescription' acc ('[] :: [Type]) = acc |
FoldDescription' acc (Description desc ': mods) = FoldDescription' desc mods |
FoldDescription' acc (mod ': mods) = FoldDescription' acc mods |

reflectDescription :: forall (mods :: [Type]). KnownSymbol (FoldDescription mods) => Proxy mods -> String #

Reflect description to the term level.

    >>> reflectDescription (Proxy :: Proxy '[Required, Description "foobar", Lenient])
    "foobar"