Documentation says default format is :json, but it responds differently when it's explicitly specified

[ian-kelling]

When I have this:
add_swagger_documentation api_version: 'v1', mount_path: '/api_docs'
$ curl url/api_docs
I get a ruby hash string.
$ curl url/api_docs.json
I get a json document

add_swagger_documentation api_version: 'v1', mount_path: '/api_docs', format: :json
$ curl url/api_docs
I get a json document
$ curl url/api_docs.json
I get 404

The documentation claims that the first should be identical to the second (that is the meaning of a default).

And of course, the documentation claims the response format will be json by default, but I got a ruby hash in a string.

[dblock]

So is the unexpected part the 404 when you try to get the .json one in the second example and get back a 404?

The swagger docs are mounted within a Grape API, so there's the format of the documentation, but then there's the whole request/accept negotiation of the content format in the way.

[ian-kelling]

Your docs say a == b, when actually a != b. And you ask whether a or b is unexpected... neither, the expectation is that the docs match the behaviour. The solution is to change either a or b or the docs. I did not propose which of the 3 should happen.

And then separately, docs claim json will be output but it's not. Again, I do not propose a solution.

I think my report was pretty clear.

[dblock]

I am all for making this clear, but someone other than me needs to dig into this and figure out whether and what should be fixed.