org.apache.juneau.dto.swagger.Operation Maven / Gradle / Ivy
// ***************************************************************************************************************************
// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file *
// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file *
// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance *
// * with the License. You may obtain a copy of the License at *
// * *
// * http://www.apache.org/licenses/LICENSE-2.0 *
// * *
// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an *
// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the *
// * specific language governing permissions and limitations under the License. *
// ***************************************************************************************************************************
package org.apache.juneau.dto.swagger;
import static org.apache.juneau.common.internal.StringUtils.*;
import static org.apache.juneau.internal.CollectionUtils.*;
import static org.apache.juneau.internal.ConverterUtils.*;
import java.util.*;
import org.apache.juneau.*;
import org.apache.juneau.annotation.*;
import org.apache.juneau.internal.*;
/**
* Describes a single API operation on a path.
*
* Example:
*
* // Construct using SwaggerBuilder.
* Operation operation = operation ()
* .tags("pet" )
* .summary("Updates a pet in the store with form data" )
* .description("" )
* .operationId("updatePetWithForm" )
* .consumes("application/x-www-form-urlencoded" )
* .produces("application/json" , "application/xml" )
* .parameters(
* parameter ()
* .name("petId" )
* .in("path" )
* .description("ID of pet that needs to be updated" )
* .required(true )
* .type("string" ),
* parameter ()
* .name("name" )
* .in("formData" )
* .description("Updated name of the pet" )
* .required(false )
* .type("string" ),
* parameter ()
* .name("status" )
* .in("formData" )
* .description("Updated status of the pet" )
* .required(false )
* .type("string" )
* )
* .response(200, responseInfo ("Pet updated." ))
* .response(405, responseInfo ("Invalid input." ))
* .security("petstore_auth" , "write:pets" , "read:pets" );
*
* // Serialize using JsonSerializer.
* String json = JsonSerializer.DEFAULT .toString(operation );
*
* // Or just use toString() which does the same as above.
* json = operation .toString();
*
*
* // Output
* {
* "tags" : [
* "pet"
* ],
* "summary" : "Updates a pet in the store with form data" ,
* "description" : "" ,
* "operationId" : "updatePetWithForm" ,
* "consumes" : [
* "application/x-www-form-urlencoded"
* ],
* "produces" : [
* "application/json" ,
* "application/xml"
* ],
* "parameters" : [
* {
* "name" : "petId" ,
* "in" : "path" ,
* "description" : "ID of pet that needs to be updated" ,
* "required" : true ,
* "type" : "string"
* },
* {
* "name" : "name" ,
* "in" : "formData" ,
* "description" : "Updated name of the pet" ,
* "required" : false ,
* "type" : "string"
* },
* {
* "name" : "status" ,
* "in" : "formData" ,
* "description" : "Updated status of the pet" ,
* "required" : false ,
* "type" : "string"
* }
* ],
* "responses" : {
* "200" : {
* "description" : "Pet updated."
* },
* "405" : {
* "description" : "Invalid input"
* }
* },
* "security" : [
* {
* "petstore_auth" : [
* "write:pets" ,
* "read:pets"
* ]
* }
* ]
* }
*
*
* See Also:
*/
@Bean(properties="operationId,summary,description,tags,externalDocs,consumes,produces,parameters,responses,schemes,deprecated,security,*")
@FluentSetters
public class Operation extends SwaggerElement {
private String
summary,
description,
operationId;
private Boolean deprecated;
private ExternalDocumentation externalDocs;
private Set
tags,
schemes;
private Set
consumes,
produces;
private List parameters;
private List>> security;
private Map responses;
/**
* Default constructor.
*/
public Operation() {}
/**
* Copy constructor.
*
* @param copyFrom The object to copy.
*/
public Operation(Operation copyFrom) {
super(copyFrom);
this.consumes = copyOf(copyFrom.consumes);
this.deprecated = copyFrom.deprecated;
this.description = copyFrom.description;
this.externalDocs = copyFrom.externalDocs == null ? null : copyFrom.externalDocs.copy();
this.operationId = copyFrom.operationId;
this.produces = copyOf(copyFrom.produces);
this.schemes = copyOf(copyFrom.schemes);
this.summary = copyFrom.summary;
this.tags = copyOf(copyFrom.tags);
if (copyFrom.parameters == null) {
this.parameters = null;
} else {
this.parameters = list();
copyFrom.parameters.forEach(x -> this.parameters.add(x.copy()));
}
if (copyFrom.responses == null) {
this.responses = null;
} else {
this.responses = map();
copyFrom.responses.forEach((k,v) -> this.responses.put(k, v.copy()));
}
if (copyFrom.security == null) {
this.security = null;
} else {
this.security = list();
copyFrom.security.forEach(x -> {
Map> m2 = map();
x.forEach((k,v) -> m2.put(k, copyOf(v)));
this.security.add(m2);
});
}
}
/**
* Make a deep copy of this object.
*
* @return A deep copy of this object.
*/
public Operation copy() {
return new Operation(this);
}
//-----------------------------------------------------------------------------------------------------------------
// Properties
//-----------------------------------------------------------------------------------------------------------------
/**
* Bean property getter: consumes .
*
*
* A list of MIME types the operation can consume.
*
* @return The property value, or null if it is not set.
*/
public Set getConsumes() {
return consumes;
}
/**
* Bean property setter: consumes .
*
*
* A list of MIME types the operation can consume.
*
* @param value
* The new value for this property.
*
Values MUST be as described under Swagger Mime Types.
*
Can be null to unset the property.
* @return This object.
*/
public Operation setConsumes(Collection value) {
consumes = setFrom(value);
return this;
}
/**
* Bean property setter: consumes .
*
*
* A list of MIME types the operation can consume.
*
* @param value
* The new value for this property.
*
Values MUST be as described under Swagger Mime Types.
* @return This object.
*/
public Operation setConsumes(MediaType...value) {
return setConsumes(Arrays.asList(value));
}
/**
* Bean property fluent setter: consumes .
*
*
* A list of MIME types the operation can consume.
*
* @param value
* The new value for this property.
* @return This object.
*/
public Operation addConsumes(MediaType...value) {
setConsumes(setBuilder(MediaType.class).sparse().add(value).build());
return this;
}
/**
* Bean property getter: deprecated .
*
*
* Declares this operation to be deprecated.
*
* @return The property value, or null if it is not set.
*/
public Boolean getDeprecated() {
return deprecated;
}
/**
* Bean property getter: deprecated .
*
*
* Declares this operation to be deprecated.
*
* @return The property value, or false if it is not set.
*/
public boolean isDeprecated() {
return deprecated != null && deprecated == true;
}
/**
* Bean property setter: deprecated .
*
*
* Declares this operation to be deprecated.
*
* @param value The new value for this property.
* @return This object.
*/
public Operation setDeprecated(Boolean value) {
deprecated = value;
return this;
}
/**
* Bean property getter: description .
*
*
* A verbose explanation of the operation behavior.
*
* @return The property value, or null if it is not set.
*/
public String getDescription() {
return description;
}
/**
* Bean property setter: description .
*
*
* A verbose explanation of the operation behavior.
*
* @param value
* The new value for this property.
*
GFM syntax can be used for rich text representation.
*
Can be null to unset the property.
* @return This object.
*/
public Operation setDescription(String value) {
description = value;
return this;
}
/**
* Bean property getter: externalDocs .
*
*
* Additional external documentation for this operation.
*
* @return The property value, or null if it is not set.
*/
public ExternalDocumentation getExternalDocs() {
return externalDocs;
}
/**
* Bean property setter: externalDocs .
*
*
* Additional external documentation for this operation.
*
* @param value
* The values to add to this property.
*
Can be null to unset the property.
* @return This object.
*/
public Operation setExternalDocs(ExternalDocumentation value) {
externalDocs = value;
return this;
}
/**
* Bean property getter: operationId .
*
*
* Unique string used to identify the operation.
*
* @return The property value, or null if it is not set.
*/
public String getOperationId() {
return operationId;
}
/**
* Bean property setter: operationId .
*
*
* Unique string used to identify the operation.
*
* @param value
* The new value for this property.
*
The id MUST be unique among all operations described in the API.
*
Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is recommended to
* follow common programming naming conventions.
*
Can be null to unset the property.
* @return This object.
*/
public Operation setOperationId(String value) {
operationId = value;
return this;
}
/**
* Bean property getter: parameters .
*
*
* A list of parameters that are applicable for this operation.
*
*
Notes:
* -
* If a parameter is already defined at the Path Item,
* the new definition will override it, but can never remove it.
*
-
* The list MUST NOT include duplicated parameters.
*
-
* A unique parameter is defined by a combination of a
name and location .
* -
* The list can use the Swagger Reference Object
* to link to parameters that are defined at the Swagger Object's parameters.
*
-
* There can be one
"body" parameter at most.
*
*
* @return The property value, or null if it is not set.
*/
public List getParameters() {
return parameters;
}
/**
* Returns the parameter with the specified type and name.
*
* @param in The parameter in.
* @param name The parameter name. Can be null for parameter type body .
* @return The matching parameter info, or null if not found.
*/
public ParameterInfo getParameter(String in, String name) {
if (parameters != null)
for (ParameterInfo pi : parameters)
if (eq(pi.getIn(), in))
if (eq(pi.getName(), name) || "body".equals(pi.getIn()))
return pi;
return null;
}
/**
* Bean property setter: parameters .
*
*
* A list of parameters that are applicable for this operation.
*
* @param value
* The new value for this property.
*
Can be null to unset the property.
* @return This object.
*/
public Operation setParameters(Collection value) {
parameters = listFrom(value);
return this;
}
/**
* Bean property setter: parameters .
*
*
* A list of parameters that are applicable for this operation.
*
* @param value
* The new value for this property.
* @return This object.
*/
public Operation setParameters(ParameterInfo...value) {
return setParameters(Arrays.asList(value));
}
/**
* Bean property fluent setter: parameters .
*
*
* A list of parameters that are applicable for this operation.
*
* @param value
* The new value for this property.
* @return This object.
*/
public Operation addParameters(ParameterInfo...value) {
setParameters(listBuilder(ParameterInfo.class).sparse().add(value).build());
return this;
}
//-----------------------------------------------------------------------------------------------------------------
// produces
//-----------------------------------------------------------------------------------------------------------------
/**
* Bean property getter: produces .
*
*
* A list of MIME types the operation can produce.
*
* @return The property value, or null if it is not set.
*/
public Set getProduces() {
return produces;
}
/**
* Bean property setter: produces .
*
*
* A list of MIME types the operation can produce.
*
* @param value
* The new value for this property.
*
Value MUST be as described under Swagger Mime Types.
*
Can be null to unset the property.
* @return This object.
*/
public Operation setProduces(Collection value) {
produces = setFrom(value);
return this;
}
/**
* Bean property setter: produces .
*
*
* A list of MIME types the operation can produce.
*
* @param value
* The new value for this property.
*
Value MUST be as described under Swagger Mime Types.
* @return This object.
*/
public Operation setProduces(MediaType...value) {
return setProduces(Arrays.asList(value));
}
/**
* Bean property fluent setter: produces .
*
*
* A list of MIME types the operation can produce.
*
* @param value
* The new value for this property.
* @return This object.
*/
public Operation addProduces(MediaType...value) {
setProduces(setBuilder(MediaType.class).sparse().add(value).build());
return this;
}
/**
* Bean property getter: responses .
*
*
* The list of possible responses as they are returned from executing this operation.
*
* @return The property value, or null if it is not set.
*/
public Map getResponses() {
return responses;
}
/**
* Returns the response info with the given status code.
*
* @param status The HTTP status code.
* @return The response info, or null if not found.
*/
public ResponseInfo getResponse(String status) {
if (responses != null)
return responses.get(status);
return null;
}
/**
* Returns the response info with the given status code.
*
* @param status The HTTP status code.
* @return The response info, or null if not found.
*/
public ResponseInfo getResponse(int status) {
return getResponse(String.valueOf(status));
}
/**
* Bean property setter: responses .
*
*
* The list of possible responses as they are returned from executing this operation.
*
* @param value
* The new value for this property.
*
Property value is required.
* @return This object.
*/
public Operation setResponses(Map value) {
responses = copyOf(value);
return this;
}
/**
* Adds a single value to the responses property.
*
* @param statusCode The HTTP status code.
* @param response The response description.
* @return This object.
*/
public Operation addResponse(String statusCode, ResponseInfo response) {
responses = mapBuilder(responses).add(statusCode, response).build();
return this;
}
/**
* Bean property getter: schemes .
*
*
* The transfer protocol for the operation.
*
* @return The property value, or null if it is not set.
*/
public Set getSchemes() {
return schemes;
}
/**
* Bean property setter: schemes .
*
*
* The transfer protocol for the operation.
*
* @param value
* The new value for this property.
*
Valid values:
*
* "http"
* "https"
* "ws"
* "wss"
*
*
Can be null to unset the property.
* @return This object.
*/
public Operation setSchemes(Collection value) {
schemes = setFrom(value);
return this;
}
/**
* Bean property fluent setter: schemes .
*
*
* The transfer protocol for the operation.
*
* @param value
* The new value for this property.
*
String values can also be JSON arrays.
* @return This object.
*/
public Operation addSchemes(String...value) {
setSchemes(setBuilder(String.class).sparse().addJson(value).build());
return this;
}
/**
* Bean property getter: security .
*
*
* A declaration of which security schemes are applied for this operation.
*
* @return The property value, or null if it is not set.
*/
public List>> getSecurity() {
return security;
}
/**
* Bean property setter: security .
*
*
* A declaration of which security schemes are applied for this operation.
*
* @param value
* The new value for this property.
*
Can be null to unset the property.
* @return This object.
*/
public Operation setSecurity(Collection>> value) {
security = listFrom(value);
return this;
}
/**
* Same as {@link #addSecurity(String, String...)}.
*
* @param scheme
* The scheme name.
* @param alternatives
* The list of values describes alternative security schemes that can be used (that is, there is a logical OR
* between the security requirements).
* @return This object.
*/
public Operation addSecurity(String scheme, String...alternatives) {
Map> m = map();
m.put(scheme, alist(alternatives));
security = listBuilder(security).add(m).build();
return this;
}
/**
* Bean property getter: summary .
*
*
* A short summary of what the operation does.
*
* @return The property value, or null if it is not set.
*/
public String getSummary() {
return summary;
}
/**
* Bean property setter: summary .
*
*
* A short summary of what the operation does.
*
* @param value
* The new value for this property.
*
Can be null to unset the property.
* @return This object.
*/
public Operation setSummary(String value) {
summary = value;
return this;
}
/**
* Bean property getter: tags .
*
*
* A list of tags for API documentation control.
*
Tags can be used for logical grouping of operations by resources or any other qualifier.
*
* @return The property value, or null if it is not set.
*/
public Set getTags() {
return tags;
}
/**
* Bean property setter: tags .
*
*
* A list of tags for API documentation control.
*
Tags can be used for logical grouping of operations by resources or any other qualifier.
*
* @param value
* The new value for this property.
*
Can be null to unset the property.
* @return This object.
*/
public Operation setTags(Collection value) {
tags = setFrom(value);
return this;
}
/**
* Bean property fluent setter: tags .
*
*
* A list of tags for API documentation control.
*
Tags can be used for logical grouping of operations by resources or any other qualifier.
*
* @param value
* The new value for this property.
* @return This object.
*/
public Operation setTags(String...value) {
setTags(setBuilder(String.class).sparse().add(value).build());
return this;
}
/**
* Bean property fluent adder: tags .
*
*
* A list of tags for API documentation control.
*
Tags can be used for logical grouping of operations by resources or any other qualifier.
*
* @param value
* The values to add to this property.
* @return This object.
*/
public Operation addTags(String...value) {
setTags(setBuilder(tags).sparse().add(value).build());
return this;
}
//
//
@Override /* SwaggerElement */
public T get(String property, Class type) {
if (property == null)
return null;
switch (property) {
case "consumes": return toType(getConsumes(), type);
case "deprecated": return toType(getDeprecated(), type);
case "description": return toType(getDescription(), type);
case "externalDocs": return toType(getExternalDocs(), type);
case "operationId": return toType(getOperationId(), type);
case "parameters": return toType(getParameters(), type);
case "produces": return toType(getProduces(), type);
case "responses": return toType(getResponses(), type);
case "schemes": return toType(getSchemes(), type);
case "security": return toType(getSecurity(), type);
case "summary": return toType(getSummary(), type);
case "tags": return toType(getTags(), type);
default: return super.get(property, type);
}
}
@SuppressWarnings({"unchecked","rawtypes"})
@Override /* SwaggerElement */
public Operation set(String property, Object value) {
if (property == null)
return this;
switch (property) {
case "consumes": return setConsumes(listBuilder(MediaType.class).sparse().addAny(value).build());
case "deprecated": return setDeprecated(toBoolean(value));
case "description": return setDescription(stringify(value));
case "externalDocs": return setExternalDocs(toType(value, ExternalDocumentation.class));
case "operationId": return setOperationId(stringify(value));
case "parameters": return setParameters(listBuilder(ParameterInfo.class).sparse().addAny(value).build());
case "produces": return setProduces(listBuilder(MediaType.class).sparse().addAny(value).build());
case "responses": return setResponses(mapBuilder(String.class,ResponseInfo.class).sparse().addAny(value).build());
case "schemes": return setSchemes(listBuilder(String.class).sparse().addAny(value).build());
case "security": return setSecurity((List)listBuilder(Map.class,String.class,List.class,String.class).sparse().addAny(value).build());
case "summary": return setSummary(stringify(value));
case "tags": return setTags(listBuilder(String.class).sparse().addAny(value).build());
default:
super.set(property, value);
return this;
}
}
@Override /* SwaggerElement */
public Set keySet() {
Set s = setBuilder(String.class)
.addIf(consumes != null, "consumes")
.addIf(deprecated != null, "deprecated")
.addIf(description != null, "description")
.addIf(externalDocs != null, "externalDocs")
.addIf(operationId != null, "operationId")
.addIf(parameters != null, "parameters")
.addIf(produces != null, "produces")
.addIf(responses != null, "responses")
.addIf(schemes != null, "schemes")
.addIf(security != null, "security")
.addIf(summary != null, "summary")
.addIf(tags != null, "tags")
.build();
return new MultiSet<>(s, super.keySet());
}
}