Add default endpoint descriptions

[fizruk]

Writing endpoint descriptions is important, but sometimes we don't do this.
This is fine for default Swagger UI, but some more fancy versions (like https://github.com/jensoleg/swagger-ui) don't display the list of endpoints nicely when there are no descriptions:

So maybe we should provide some mechanism to generate at least some sort of descriptions
(semi-)automatically.

[phadej]

I remember there was discussion about Description "foo" :> subapi swagger combinator. Was it rejected since?

Though default endpoint would be still cool

[saevarb]

Hi. I think this library is enormously awesome, except for the fact that it doesn't automatically generate any endpoint descriptions or operation IDs for the endpoints.

The swagger specification says that operation IDs may be used by clients to uniquely identify endpoints. This causes libraries like martian to not return any endpoints, because it uses the operation IDs to construct the structure which contains the endpoints(An operation with ID "fooBar" lets me call that endpoint using a keyword :foo-bar).

I would definitely be willing to look into implementing this, but I'm not familiar with the type-level magic that is going on, and I'm not sure I'm willing to spend too much time on it if it's too complicated. Do you guys have a recommended starting point for adding such combinators? Also, if I were to implement support for, say, a Desc and an OperationId combinators, what would the preferred usage scenario look like? Just type Foo = MyEndpoint :> Desc "Endpoint" :> OpId "getFoo"? Would it require a new type operator? And I gather that these combinators would not be compatible with servant as-is, and would need to be removed by some type-level machinery before passing them on?

[fizruk]

Disclaimer: this code is untested.

To add a description combinator you can do this:

-- | Add a description for a (part of) API.
data Description (sym :: Symbol)

-- | A handy infix version of 'Description'.
type (--|) api sym = Description sym :> api

type MyAPI
    = GetResource    --| "Get resource by ID."
 :<|> DeleteResource --| "Delete resource by ID."

type GetResource    = QueryParam "resource_id" ResourceId :> Get    '[JSON] Resource
type DeleteResource = QueryParam "resource_id" ResourceId :> Delete '[JSON] Resource

-- or

type MyAPI = GetResource :<|> DeleteResource

type GetResource
  = Description "Get resource by ID."
 :> QueryParam "resource_id" ResourceId
 :> Get '[JSON] Resource

type DeleteResource
  = Description "Delete resource by ID."
 :> QueryParam "resource_id" ResourceId
 :> Delete '[JSON] Resource

Instances for Description:

{-# LANGUAGE ScopedTypeVariables #-}

instance HasServer api => HasServer (Description desc :> api) where
  type ServerT (Description desc :> api) m = ServerT api m
  route _ = route (Proxy :: Proxy api)

instance HasClient api => HasClient (Description desc :> api) where
  type Client (Description desc :> api) = Client api
  clientWithRoute _ = clientWithRoute (Proxy :: Proxy api)

instance HasSwagger api => HasSwagger (Description desc :> api) where
  toSwagger _ = toSwagger (Proxy :: Proxy api)
    & allOperations.description %~ (Just (symbolVal (Proxy :: Proxy desc)) <>)

It is possible that you want summary instead of description in HasSwagger instance.

[KtorZ]

Hey!

For those still interested, the following actually works fine for me (thanks @fizruk):

import           Control.Lens         ((&), (?~))
import           GHC.TypeLits         (KnownSymbol, Symbol)
import           Servant              ((:>), HasServer, ServerT)
import           Data.Proxy           (Proxy (..))
import           Data.Swagger         (ToSchema)

import qualified Data.Swagger         as Swagger
import qualified Data.Text            as Text
import qualified GHC.TypeLits         as GHC
import qualified Servant
import qualified Servant.Swagger      as Servant


data Description (desc :: Symbol)


type (--|) api desc =
  Description desc :> api


instance HasServer api ctx => HasServer (Description desc :> api) ctx where
  type ServerT (Description desc :> api) m =
    ServerT api m

  route _ =
    Servant.route (Proxy :: Proxy api)


instance (KnownSymbol desc, HasSwagger api) => HasSwagger (Description desc :> api) where
  toSwagger _ =
    Servant.toSwagger (Proxy :: Proxy api)
      & Swagger.allOperations . Swagger.description ?~ Text.pack (GHC.symbolVal (Proxy :: Proxy desc))

[akhesaCaro]

Hi,
Servant-swagger will be moved into the main Servant repo (see : haskell-servant/servant#1475)
If this issue is still relevant, would it be possible for you to summit it there? : https://github.com/haskell-servant/servant/issues

Thanks in advance!