Plumber: Swagger parameters listed in reverse order

[alexzaytsev-newsroomly]

My method has a bunch of parameters like so:

#* @post /dosomething
do_something <- function(par1, dataframe, somebool = TRUE, someint = 0)
{}

However, when i launch the plumber server using the sample code provided, swagger shows 'no parameters' for my action?

What should i add to list them.

[dselivanov]

@trestletech same issue. Is there any instruction how to point swagger to show parameters? do we miss something?

[jeffkeller87]

The documentation for decorating code to generate Swagger documentation needs a lot of work, but I've discovered a few decorations so far from this example. The one you are looking for is @param.

#' @param par1 description text

Note: you can use #' instead of #* if you like.

Strangely, parameters documented this way appear in reverse order in the rendered Swagger document. So to get them to appear in the way you are likely familiar with, your code would look something like this:

#' @post /dosomething
#' @param someint description
#' @param somebool description
#' @param dataframe description
#' @param par1 description
do_something <- function(par1, dataframe, somebool = TRUE, someint = 0)
{}

Some others you might find useful:

#' @apiTitle Title text
#' @apiDescription Description text

[trestletech]

Sorry I'm so late to the party, and thanks for the tip @jeffkeller87 .

PRs welcomed on the docs to start fleshing this stuff out.

I just renamed the ticket and I'll keep it open to note the bug pointed out above that parameters are in reverse order. That seems like something we should fix.

[meztez]

A simple fix for that would be to do rev(params) there

https://github.com/rstudio/plumber/blob/b7ff05ac6bd21db3341a9a91fb90c4c581bf56b9/R/parse-block.R#L229

[mskyttner]

Using plumber 1.0, it seems "multiline" summary descriptions in endpoint annotations still get reversed in the generated docs?

In the screenshot the endpoint summary description is broken into two lines (upper part of picture), which get reversed in the docs (green field, lower part of picture).

Does everything in the annotation need to go into one long line?

This document http://spec.openapis.org/oas/v3.0.3#fixed-fields-6 has two fields described:

summary: An optional, string summary, intended to apply to all operations in this path.
description: An optional, string description, intended to apply to all operations in this path. CommonMark syntax MAY be used for rich text representation.

Could #' @description My description and some CommonMark in a multiline block be used when documenting an API endpoint with annotations?

[meztez]

Yes this is still the case in plumber 1.0.0, I believe we only fixed params and another one. I don't think we modified the parse block. it is a simple fix. will PR