Swagger Parameters

Expanding operations shows you a list of parameters.

Parameter information can be defined in a couple of ways. The typical way is through annotations on parameters being passed to your @RestOp-annotated method, like so:

@RestGet
public Collection<Pet> getPets(
        @Query(
            name="s",
            schema=@Schema(
                description={
                    "Search.",
                    "Key/value pairs representing column names and search tokens.",
                    "'*' and '?' can be used as meta-characters in string fields.",
                    "'>', '>=', '<', and '<=' can be used as limits on numeric and date fields.",
                    "Date fields can be matched with partial dates (e.g. '2018' to match any date in the year 2018)."
                },
                type="array",
                collectionFormat="csv"
            )
        )
        String[] s,
        @Query(
            name="v",
            schema=@Schema(
                description={
                    "View.",
                    "Column names to display."
                },
                type="array",
                collectionFormat="csv"
            )
        )
        String[] v,
        ...
    ) {
    ...
}

note

• The @Schema annotation can also be attached directly to the parameter or parameter type as well.
• The type and collectionFormat values above are optional and auto-detected based on the parameter class type if omitted. They're included here for clarity. The examples will be explained in the next section.

Another option is to specify your parameter information in the parameters annotation as free-form JSON 5.

The Queryable converter class ships a canned SWAGGER_PARAMS constant with this exact information pre-built, so resources that use Queryable don't have to hand-write it. LogsResource (juneau-microservice-examples) does exactly this:

LogsResource.viewParsedEntries()

@RestOp(
    method="PARSE",
    path="/*",
    summary="View parsed contents of file",
    converters=Queryable.class,
    swagger=@OpSwagger(
        parameters={
            Queryable.SWAGGER_PARAMS
        }
    )
)
public LogParser viewParsedEntries(...) {
    ...
}

Queryable.SWAGGER_PARAMS

public class Queryable implements RestConverter {

    public static final String SWAGGER_PARAMS = """
        {
            in:'query',
            name:'search',
            description:'Search expression: comma-separated column=expression clauses, e.g.
                name=$contains(smith),age=$gte(18). See the BeanQuery search language docs:
                https://juneau.apache.org/docs/topics/JuneauCommonsBeanQuery',
            type:'string',
            examples:{example:'?search=name=$contains(smith),age=$gte(18)'}
        },{
            in:'query',
            name:'view',
            description:'Comma-separated columns to return, in order.',
            type:'string',
            examples:{example:'?view=name,age'}
        },{
            in:'query',
            name:'sort',
            description:'Comma-separated sort columns.
                Append \\':desc\\' (or \\'-\\') for descending.
                The default is ascending order.',
            type:'string',
            examples:{example:'?sort=name,age:desc'}
        },{
            in:'query',
            name:'position',
            description:'0-based index of the first row.',
            type:'integer',
            minimum:0,
            examples:{example:'?position=20'}
        },{
            in:'query',
            name:'limit',
            description:'Maximum rows to return.
                Defaults and caps are set by the server.',
            type:'integer',
            examples:{example:'?limit=10'}
        },{
            in:'query',
            name:'opts',
            description:'Options as key=value clauses, e.g. counts=true.',
            type:'string',
            examples:{example:'?opts=counts=true'}
        }""";
}

This information could have also been defined in the Swagger JSON for the resource as well.

note

If you take a BeanQueryRequest method argument instead of using Queryable, you do not need this constant: each getter on BeanQueryRequest already carries a @Schema description (and position carries minimum=0), so the same six parameters appear in the generated Swagger automatically.

The parameter section contains information about the request body as well for PUT and POST methods, as shown here:

@RestPost(
    path="/pets",
    summary="Add a new pet to the store",
    swagger=@OpSwagger(
        tags="pet"
    )
)
public Pet createPet(
        @Content
        @Schema(description="Pet object to add to the store")
        Pet pet
    ) {
    return store.createPet(pet);
}

Note that the schema information on the body parameter is automatically detected if not provided.