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 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,
        ...
    ) throws NotAcceptable {
    ...
}

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.

In the case of the PetStoreResource.getPets() method, we pull this information from a static field defined in the Queryable class:

PetStoreResource.getPets()

@RestGet(
    path="/pet",
    summary="All pets in the store",
    swagger=@OpSwagger(
        tags="pet",
        parameters={
            Queryable.SWAGGER_PARAMS
        }
    ),
    ...
    converters={Queryable.class}
)
public Collection getPets() throws NotAcceptable {
    return store.getPets();
}

Queryable

public class Queryable implements RestConverter {

    public static final String SWAGGER_PARAMS=""
        + "{"
            + "in:'query',"
            + "name:'s',"
            + "description:'"
                + "Search.\n"
                + "Key/value pairs representing column names and search tokens.\n"
                + "\\'*\\' and \\'?\\' can be used as meta-characters in string fields.\n"
                + "\\'>\\', \\'>=\\', \\'2000'}"
        + "},"
        + "{"
            + "in:'query',"
            + "name:'v',"
            + "description:'"
                + "View.\n"
                + "Column names to display."
            + "',"
            + "type:'array',"
            + "collectionFormat:'csv',"
            + "x-examples:{example:'?v=name,birthDate'}"
        + "},"

        ...
    ;
}

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

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

@RestPost(
    summary="Add a new pet to the store",
    swagger=@OpSwagger(
        tags="pet"
    )
)
public Ok postPet(
        @Content
        @Schema(description="Pet object to add to the store")
        PetCreate pet
    ) throws IdConflict, NotAcceptable, UnsupportedMediaType {

    store.create(pet);
    return OK;
}

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