OpenApi : how to add descriptions to route parameters

#1

I am using Servant.OpenApi.toOpenApi to generate an OpenApi (i.e, “Swagger”) description. In the example that follows, the api variable holds the generated description.

I have figured out how to use operationsOf to add a description to a route of the generated OpenApi description via:

  let sub2 = (mempty :: OpenApi) & paths  .~
             IOHM.fromList [("/vcp/createSignerData/{numMsgs}", mempty & post ?~ mempty)]
  putStrLn "SUB2"
  putLBSLn $ A.encode $ api & operationsOf sub2 . description ?~ "SUB2 FOO--------------"

But I can’t figure out how to add descriptions to path and/or query parameters (e.g., numMsgs in this example) for that route.

#2

I don’t see any numMsgs in the example you’ve given, but it should be as easy as doing the following in the path definition:

type GetUser =
    "user" :>
    QueryParam' [Optional, Strict, ParamDescription] "id" UserId :>
    Get '[JSON] User

type ParamDescription =
    Description "Put here whatever you want about the query parameter"

Same with Header' '[Description "..."], Capture' '[Description "..."], etc.

See THIS for some examples of how to give the path in its entirety a description.
Basically, just put the Description "..." in the :> ... :> definition of your path.

1 Like
#3

That is certainly the right way (especially compared to the tortured thing I was doing). Thanks!