search

haskell-servant / servant-swagger

Swagger for Servant
http://hackage.haskell.org/package/servant-swagger
BSD 3-Clause "New" or "Revised" License
124 stars 37 forks source link

How can I add a description for a Header' '[Required, Strict] #122

Open Gau-thier opened 4 years ago

Gau-thier commented 4 years ago

In our APIs, we have one header which is declared as required because it is automatically added by our API Management.

Since none of the request will be done directly to our endpoint (100% pass through API Management), we find this confusing for our clients to have this header as required in our Swagger. We would like to add a description like:

added by API Management, do not care

Moreover, as we do not control anything on this header, it cannot be invalid: image

should be hidden (or even not generated).

Thanks!

sir4ur0n commented 4 years ago

Though this feature is not well documented (in my opinion :smile: ), you can add a description to pretty much everything, usually by using the more generic ' version, which allows to pass a Description:

QueryParam' '[Required, Strict, Description "My description!"] "foobar"

image

Capture' '[Description "My description!"] "foobar"

image

Header' '[Required, Strict, Description "My description!"] "foobar"

image

akhesaCaro commented 2 years ago

Hi, Servant-swagger will be moved into the main Servant repo (see : https://github.com/haskell-servant/servant/pull/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!