io.muserver.openapi.ParameterObjectBuilder Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of mu-server Show documentation
Show all versions of mu-server Show documentation
A simple but powerful web server framework
package io.muserver.openapi;
import java.util.Map;
/**
* Describes a single operation parameter.
* A unique parameter is defined by a combination of a name and {@link ParameterObjectBuilder#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.
*
*/
public class ParameterObjectBuilder {
private String name;
private String in;
private String description;
private Boolean required;
private boolean deprecated;
private boolean allowEmptyValue;
private String style;
private Boolean explode;
private boolean allowReserved;
private SchemaObject schema;
private Object example;
private Map examples;
private Map content;
/**
* @param 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 {@link 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.
*
* @return The current builder
*/
public ParameterObjectBuilder withName(String name) {
this.name = name;
return this;
}
/**
* @param in REQUIRED. The location of the parameter. Possible values are "query", "header", "path" or "cookie".
* @return The current builder
*/
public ParameterObjectBuilder withIn(String in) {
this.in = in;
return this;
}
/**
* @param description A brief description of the parameter. This could contain examples of use.
* CommonMark syntax MAY be used for rich text representation.
* @return The current builder
*/
public ParameterObjectBuilder withDescription(String description) {
this.description = description;
return this;
}
/**
* @param 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.
* @return The current builder
*/
public ParameterObjectBuilder withRequired(Boolean required) {
this.required = required;
return this;
}
/**
* @param deprecated Specifies that a parameter is deprecated and SHOULD be transitioned out of usage.
* @return The current builder
*/
public ParameterObjectBuilder withDeprecated(boolean deprecated) {
this.deprecated = deprecated;
return this;
}
/**
* @param 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.
* @return The current builder
*/
public ParameterObjectBuilder withAllowEmptyValue(boolean allowEmptyValue) {
this.allowEmptyValue = allowEmptyValue;
return this;
}
/**
* @param 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.
*
*
*
* styletypeinComments
*
*
*
*
* matrix
* primitive, array, objectpathPath-style parameters defined by RFC6570
*
*
* label
* primitive, array, objectpathLabel style parameters defined by RFC6570
*
*
* form
* primitive, array, objectquery, cookieForm 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
* arraypath, headerSimple style parameters defined by RFC6570. This option replaces collectionFormat with a csv value from OpenAPI 2.0.
*
*
* spaceDelimited
* arrayquerySpace separated array values. This option replaces collectionFormat equal to ssv from OpenAPI 2.0.
*
*
* pipeDelimited
* arrayqueryPipe separated array values. This option replaces collectionFormat equal to pipes from OpenAPI 2.0.
*
*
* deepObject
* objectqueryProvides a simple way of rendering nested objects using form parameters.
*
*
*
* @return The current builder
*/
public ParameterObjectBuilder withStyle(String style) {
this.style = style;
return this;
}
/**
* @param 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.
* @return The current builder
*/
public ParameterObjectBuilder withExplode(Boolean explode) {
this.explode = explode;
return this;
}
/**
* @param 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.
* @return The current builder
*/
public ParameterObjectBuilder withAllowReserved(boolean allowReserved) {
this.allowReserved = allowReserved;
return this;
}
/**
* @param schema The schema defining the type used for the parameter.
* @return The current builder
*/
public ParameterObjectBuilder withSchema(SchemaObject schema) {
this.schema = schema;
return this;
}
/**
* @param 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.
* @return The current builder
*/
public ParameterObjectBuilder withExample(Object example) {
this.example = example;
return this;
}
/**
* @param 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.
* @return The current builder
*/
public ParameterObjectBuilder withExamples(Map examples) {
this.examples = examples;
return this;
}
/**
* @param 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.
* @return The current builder
*/
public ParameterObjectBuilder withContent(Map content) {
this.content = content;
return this;
}
public ParameterObject build() {
Boolean explodeVal = this.explode == null ? "form".equals(style) : this.explode;
Boolean requiredVal = this.required == null ? "path".equals(in) : this.required;
return new ParameterObject(name, in, description, requiredVal, deprecated, allowEmptyValue, style, explodeVal, allowReserved, schema, example, examples, content);
}
/**
* Creates a builder for a {@link ParameterObject}
*
* @return A new builder
*/
public static ParameterObjectBuilder parameterObject() {
return new ParameterObjectBuilder();
}
}