servant-docs doesn't list all the content types unless they're in the same list

[gelisam]

Since #937, it is now possible to write

type TestApi = "greet" :> Get '[JSON]      Greet
          :<|> "greet" :> Get '[PlainText] Greet

instead of

type TestApi = "greet" :> Get '[JSON, PlainText] Greet

However, servant-docs does not yet support the new format, it only lists the content-types specified in the first copy of the endpoint.

Here is a self-contained example:

{-# LANGUAGE DataKinds, DeriveGeneric, MultiParamTypeClasses, OverloadedStrings, TypeOperators #-}
import Data.Aeson
import Data.Proxy
import Data.String.Conversions
import Data.Text (Text)
import GHC.Generics
import Servant.API
import Servant.Docs

newtype Greet = Greet Text
  deriving (Generic, Show)

instance FromJSON Greet
instance ToJSON Greet

instance MimeRender PlainText Greet where
    mimeRender Proxy (Greet s) = cs s

instance ToSample Greet where
  toSamples _ = singleSample $ Greet "hello"


type TestApi = "greet" :> Get '[JSON]      Greet
          :<|> "greet" :> Get '[PlainText] Greet

testApi :: Proxy TestApi
testApi = Proxy

main :: IO ()
main = putStrLn $ markdown $ docs testApi

The output is currently this:

# GET /greet

### Response:

- Status code 200
- Headers: []

- Supported content types are:

    - `application/json;charset=utf-8`
    - `application/json`

- Example (`application/json;charset=utf-8`, `application/json`):

    ```javascript
"hello"
    ```

But I expected this instead:

## GET /greet

### Response:

- Status code 200
- Headers: []

- Supported content types are:

    - `application/json;charset=utf-8`
    - `application/json`
    - `text/plain;charset=utf-8`

- Example (`application/json;charset=utf-8`, `application/json`):

    ```javascript
"hello"
    ```

- Example (`text/plain;charset=utf-8`):

    ```
hello
    ```

[phadej]

Better to aim high, and try to support

type TestApi = "greet" :> Verb GET 200 '[JSON]      Foo
          :<|> "greet" :> Verb GET 201 '[PlainText] Bar

i.e. status code, content-type and result-type can all be different.

[gelisam]

I think the problem is in the second mappend on this line: https://github.com/simspace/servant/blob/master/servant-docs/src/Servant/Docs/Internal.hs#L119

It uses HashMap's mappend instance, which keeps the value from the left input wherever the two HashMaps contain the same key.

[gelisam]

Hmm, there is already a combineAction function, so it looks like the solution would be to replace that mappend with HM.unionWith combineAction, however combineAction combines all of the Action fields except the response, body and content-types. I can see from git-log that combineAction used to combine everything except the response, and has later been changed to combine everything except the response, body and content-types. However, quite mysteriously, git-log does not show me the commit in which that has happened! Do you know if there is a good reason not to combine the content-types?

[gelisam]

Doesn't matter, turns out the rqtypes and rqbody fields of the relevant Actions are empty anyway, the content-types I am interested in are inside the Responses. combineAction doesn't combine the Responses because Action only has a single Response, not a list of them. But some of Response's fields are lists, they can be combined!

[gelisam]

Okay, I have a partial fix, it combines the content-types and the result types but not the status codes, because Action has only one Response and Response has only one Status.

[gelisam]

I think it would be easy to support more than one Status, but that would require making a breaking change to the markdown format, something like Status code: [200, 201] instead of Status code 200