Package io.muserver.openapi

Class ParameterObjectBuilder

  • public class ParameterObjectBuilder
extends java.lang.Object

    Describes a single operation parameter.

    A unique parameter is defined by a combination of a name and withIn(String) (location).

    Parameter Locations

    There are four possible parameter locations specified by the in field:

    • path - Used together with Path Templating, where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in /items/{itemId}, the path parameter is itemId.
    • query - Parameters that are appended to the URL. For example, in /items?id=###, the query parameter is id.
    • header - Custom headers that are expected as part of the request. Note that RFC7230 states header names are case insensitive.
    • cookie - Used to pass a specific cookie value to the API.

    • Constructor Detail

      • ParameterObjectBuilder

        public ParameterObjectBuilder()

    • Method Detail

      • withName

        public ParameterObjectBuilder withName​(java.lang.String name)
        Parameters:
        name - REQUIRED. The name of the parameter. Parameter names are case sensitive.
        • If in is "path", the name field MUST correspond to the associated path segment from the path field in the PathsObject.
        • If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition SHALL be ignored.
        • For all other cases, the name corresponds to the parameter name used by the in property.
        Returns:
        The current builder

      • withIn

        public ParameterObjectBuilder withIn​(java.lang.String in)
        Parameters:
        in - REQUIRED. The location of the parameter. Possible values are "query", "header", "path" or "cookie".
        Returns:
        The current builder

      • withDescription

        public ParameterObjectBuilder withDescription​(java.lang.String description)
        Parameters:
        description - A brief description of the parameter. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
        Returns:
        The current builder

      • withRequired

        public ParameterObjectBuilder withRequired​(java.lang.Boolean required)
        Parameters:
        required - Determines whether this parameter is mandatory. If the parameter location is "path", this property is REQUIRED and its value MUST be true. Otherwise, the property MAY be included and its default value is false.
        Returns:
        The current builder

      • withDeprecated

        public ParameterObjectBuilder withDeprecated​(java.lang.Boolean deprecated)
        Parameters:
        deprecated - Specifies that a parameter is deprecated and SHOULD be transitioned out of usage.
        Returns:
        The current builder

      • withAllowEmptyValue

        public ParameterObjectBuilder withAllowEmptyValue​(java.lang.Boolean allowEmptyValue)
        Parameters:
        allowEmptyValue - Sets the ability to pass empty-valued parameters. This is valid only for query parameters and allows sending a parameter with an empty value. Default value is false. If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue SHALL be ignored.
        Returns:
        The current builder

      • withStyle

        public ParameterObjectBuilder withStyle​(java.lang.String style)
        Parameters:
        style -

        Describes how the parameter value will be serialized depending on the type of the parameter value. Default values (based on value of in): for query - form; for path - simple; for header - simple; for cookie - form.

        In order to support common ways of serializing simple parameters, a set of style values are defined.

        Style values
        style type in Comments
        matrix primitive, array, object path Path-style parameters defined by RFC6570
        label primitive, array, object path Label style parameters defined by RFC6570
        form primitive, array, object query, cookie Form style parameters defined by RFC6570. This option replaces collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.
        simple array path, header Simple style parameters defined by RFC6570. This option replaces collectionFormat with a csv value from OpenAPI 2.0.
        spaceDelimited array query Space separated array values. This option replaces collectionFormat equal to ssv from OpenAPI 2.0.
        pipeDelimited array query Pipe separated array values. This option replaces collectionFormat equal to pipes from OpenAPI 2.0.
        deepObject object query Provides a simple way of rendering nested objects using form parameters.
        Returns:
        The current builder

      • withExplode

        public ParameterObjectBuilder withExplode​(java.lang.Boolean explode)
        Parameters:
        explode - When this is true, parameter values of type array or object generate separate parameters for each value of the array or key-value pair of the map. For other types of parameters this property has no effect. When style is form, the default value is true. For all other styles, the default value is false.
        Returns:
        The current builder

      • withAllowReserved

        public ParameterObjectBuilder withAllowReserved​(java.lang.Boolean allowReserved)
        Parameters:
        allowReserved - Determines whether the parameter value SHOULD allow reserved characters, as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.
        Returns:
        The current builder

      • withSchema

        public ParameterObjectBuilder withSchema​(SchemaObject schema)
        Parameters:
        schema - The schema defining the type used for the parameter.
        Returns:
        The current builder

      • withExample

        public ParameterObjectBuilder withExample​(java.lang.Object example)
        Parameters:
        example - Example of the media type. The example SHOULD match the specified schema and encoding properties if present. The example field is mutually exclusive of the examples field. Furthermore, if referencing a schema which contains an example, the example value SHALL override the example provided by the schema. To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.
        Returns:
        The current builder

      • withExamples

        public ParameterObjectBuilder withExamples​(java.util.Map<java.lang.String,​ExampleObject> examples)
        Parameters:
        examples - Examples of the media type. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. The examples field is mutually exclusive of the example field. Furthermore, if referencing a schema which contains an example, the examples value SHALL override the example provided by the schema.
        Returns:
        The current builder

      • withContent

        public ParameterObjectBuilder withContent​(java.util.Map<java.lang.String,​MediaTypeObject> content)
        Parameters:
        content - A map containing the representations for the parameter. The key is the media type and the value describes it. The map MUST only contain one entry.
        Returns:
        The current builder