Cookie support in servant-auth-swagger

[Superpat]

I'd like to use cookie based auth with toSwagger but I get this error

    • No instance for (Data.Swagger.Internal.ParamSchema.ToParamSchema
                             SetCookie)
       arising from a use of ‘toSwagger’
    • In the first argument of ‘(&)’, namely ‘toSwagger api’
      In the first argument of ‘(&)’, namely
        ‘toSwagger api & info . title .~ "Gramm API"’
      In the first argument of ‘(&)’, namely
        ‘toSwagger api & info . title .~ "Gramm API"
         & info . version .~ "1.0"’

What is necessary for cookie auth support? If it's not too complicated I'd be glad to take care of it.

[domenkozar]

From current Auth combinator, you can't really document much about Cookies in swagger2.

#42 has set authentication to be a noop - because swagger2.0 doesn't support Cookie authentication (on the other hand, openapi 3 does).

About documenting parameters, shortcut I use for now is a noop:

instance ToParamSchema SetCookie where
  toParamSchema _ = mempty -- TODO: document name of the cookie

Combining #116 and #58 we could come up with API combinators like AuthCookie "auth" and CSRFCookie "csrf" that would allow swagger generation to do the right thing.

[phadej]

I don't have required context. What kind of type API = ??? requires ToParamSchema?

There is ToHttpApiData SetCookie, which is used in e.g. Header "X-Foo" SetCookie :> api combinator, so the ToParamSchema should try to describe that as well as possible.

If there's some other thing where ToParamSchema is used, I'd like to know what it is. Maybe ToParamSchema is a wrong thing to use there?

[domenkozar]

I can reproduce with

#!/usr/bin/env stack
{- stack script --nix --resolver lts-12.16
  --package http-api-data
  --package servant-auth
  --package servant-auth-swagger
  --package cookie
-}

{-# LANGUAGE DataKinds #-}
{-# LANGUAGE TypeOperators #-}
{-# LANGUAGE OverloadedStrings #-}

module ApiType where

import Servant
import Servant.Auth
import Servant.Auth.Swagger ()
import Servant.Swagger
import Web.Cookie


type API = Header "X-Foo" SetCookie  :> Get '[JSON] Int

api :: Proxy API
api = Proxy

main :: IO ()
main = print (toSwagger api)

Although this doesn't pin http-api-data-0.3.10, but I've tried in my project with the correct version and it's missing the same instance.

[phadej]

Ok. so you use Header.

Then the instance for ToParamSchema should describe how SetCookie is serialised.

instance ToParamSchema SetCookie where
  toParamSchema _ = mempty
    & type_ .~ SwaggerString
    ....

[domenkozar]

There's no Cookie support in Swagger2, best effort is:

parameters:
  - name: Cookie
    in: header
    type: string
    required: true

So given SetCookie instance, we can only set that it's a string. I suppose Header will set the rest. Only in OpenAPI3 there is proper support for describing what's inside cookies.

[phadej]

I'm not so interested "what's inside the cookie", the SetCookie doesn't tell us that anyway. But we should describe what makes a valid cookie string as well as we can. At very list that it's a string :)

[domenkozar]

@phadej agreed :) I've updated the PR, it's an improvement over the current missing instance.