io.muserver.openapi

Class ParameterObjectBuilder

java.lang.Object

io.muserver.openapi.ParameterObjectBuilder

public class ParameterObjectBuilder
extends 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 Summary

Constructors

Constructor and Description
ParameterObjectBuilder()

Method Summary

Modifier and Type	Method and Description
ParameterObject	build()
static ParameterObjectBuilder	parameterObject() Creates a builder for a ParameterObject
ParameterObjectBuilder	withAllowEmptyValue(boolean allowEmptyValue)
ParameterObjectBuilder	withAllowReserved(boolean allowReserved)
ParameterObjectBuilder	withContent(Map<String,MediaTypeObject> content)
ParameterObjectBuilder	withDeprecated(boolean deprecated)
ParameterObjectBuilder	withDescription(String description)
ParameterObjectBuilder	withExample(Object example)
ParameterObjectBuilder	withExamples(Map<String,ExampleObject> examples)
ParameterObjectBuilder	withExplode(Boolean explode)
ParameterObjectBuilder	withIn(String in)
ParameterObjectBuilder	withName(String name)
ParameterObjectBuilder	withRequired(Boolean required)
ParameterObjectBuilder	withSchema(SchemaObject schema)
ParameterObjectBuilder	withStyle(String style)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ParameterObjectBuilder

public ParameterObjectBuilder()

Method Detail

withName

public ParameterObjectBuilder withName(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(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(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(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(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(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(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	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(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(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(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(Map<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(Map<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

build

public ParameterObject build()

parameterObject

public static ParameterObjectBuilder parameterObject()

Creates a builder for a ParameterObject

Returns:

A new builder