ModelImpl appendObjectPathAndModelDefinitions(final ObjectSpecification objectSpec) {
final String objectType = objectTypeFor(objectSpec);
final Path path = new Path();
swagger.path(String.format("/objects/%s/{objectId}", objectType), path);
final String tag = tagFor(objectType, null);
final Operation operation = new Operation();
path.get(operation);
operation
.tag(tag)
.description(Util.roSpec("14.1"))
.parameter(new PathParameter().name("objectId").type("string"))
.produces("application/json;profile=urn:org.apache.isis/v1")
.produces("application/json;profile=urn:org.apache.isis/v1;suppress=true")
.produces("application/json;profile=urn:org.restfulobjects:repr-types/object");
// per https://github.com/swagger-api/swagger-spec/issues/146, swagger 2.0 doesn't support
// multiple
// modelled representations per path and response code;
// in particular cannot associate representation/model with Accept header ('produces(...)
// method)
final String restfulObjectsModelDefinition = objectType + "RestfulObjectsRepr";
if (false) {
operation.response(
200,
newResponse(Caching.TRANSACTIONAL)
.description(
"if Accept: application/json;profile=urn:org.restfulobjects:repr-types/object")
.schema(newRefProperty(restfulObjectsModelDefinition)));
final ModelImpl roSpecModel =
newModel(Util.roSpec("14.4") + ": representation of " + objectType)
.property("title", stringProperty())
.property("domainType", stringProperty()._default(objectType))
.property("instanceId", stringProperty())
.property("members", new ObjectProperty());
swagger.addDefinition(restfulObjectsModelDefinition, roSpecModel);
}
final String isisModelDefinition = objectType + "Repr";
operation.response(
200,
newResponse(Caching.TRANSACTIONAL)
.description(
objectType + " , if Accept: application/json;profile=urn:org.apache.isis/v1")
.schema(newRefProperty(isisModelDefinition)));
final ModelImpl isisModel = new ModelImpl();
addDefinition(isisModelDefinition, isisModel);
// return so can be appended to
return isisModel;
}
void appendCollectionTo(
final ObjectSpecification objectSpec, final OneToManyAssociation collection) {
final String objectType = objectTypeFor(objectSpec);
final String collectionId = collection.getId();
final Path path = new Path();
swagger.path(
String.format("/objects/%s/{objectId}/collections/%s", objectType, collectionId), path);
final String tag = tagFor(objectType, null);
final Operation collectionOperation =
new Operation()
.tag(tag)
.description(Util.roSpec("17.1") + ": resource of " + objectType + "#" + collectionId)
.parameter(new PathParameter().name("objectId").type("string"))
.produces("application/json;profile=urn:org.apache.isis/v1")
.produces("application/json;profile=urn:org.apache.isis/v1;suppress=true")
.produces(
"application/json;profile=urn:org.restfulobjects:repr-types/object-collection");
path.get(collectionOperation);
collectionOperation.response(
200,
new Response()
.description(
objectType
+ "#"
+ collectionId
+ " , if Accept: application/json;profile=urn:org.apache.isis/v1")
.schema(modelFor(collection)));
}
void appendObjectActionInvokePath(
final ObjectSpecification objectSpec, final ObjectAction objectAction) {
final String objectType = objectTypeFor(objectSpec);
final String actionId = objectAction.getId();
final List<ObjectActionParameter> parameters = objectAction.getParameters();
final Path path = new Path();
swagger.path(
String.format("/objects/%s/{objectId}/actions/%s/invoke", objectType, actionId), path);
final String tag = tagFor(objectType, null);
final Operation invokeOperation =
new Operation()
.tag(tag)
.description(
Util.roSpec("19.1") + ": (invoke) resource of " + objectType + "#" + actionId)
.parameter(new PathParameter().name("objectId").type("string"))
.produces("application/json;profile=urn:org.apache.isis/v1")
.produces("application/json;profile=urn:org.apache.isis/v1;suppress=true")
.produces("application/json;profile=urn:org.restfulobjects:repr-types/action-result");
final ActionSemantics.Of semantics = objectAction.getSemantics();
if (semantics.isSafeInNature()) {
path.get(invokeOperation);
for (final ObjectActionParameter parameter : parameters) {
invokeOperation.parameter(
new QueryParameter()
.name(parameter.getId())
.description(
Util.roSpec("2.9.1")
+ (!Strings.isNullOrEmpty(parameter.getDescription())
? (": " + parameter.getDescription())
: ""))
.required(false)
.type("string"));
}
if (!parameters.isEmpty()) {
invokeOperation.parameter(
new QueryParameter()
.name("x-isis-querystring")
.description(
Util.roSpec("2.10") + ": all (formal) arguments as base64 encoded string")
.required(false)
.type("string"));
}
} else {
if (semantics.isIdempotentInNature()) {
path.put(invokeOperation);
} else {
path.post(invokeOperation);
}
final ModelImpl bodyParam = new ModelImpl().type("object");
for (final ObjectActionParameter parameter : parameters) {
final ObjectSpecification specification = parameter.getSpecification();
final Property valueProperty =
specification.isValue() ? modelFor(specification) : refToLinkModel();
bodyParam.property(
parameter.getId(), new ObjectProperty().property("value", valueProperty));
}
invokeOperation
.consumes("application/json")
.parameter(new BodyParameter().name("body").schema(bodyParam));
}
invokeOperation.response(
200,
new Response()
.description(objectType + "#" + actionId)
.schema(actionReturnTypeFor(objectAction)));
}
void appendServiceActionInvokePath(
final ObjectSpecification serviceSpec, final ObjectAction serviceAction) {
final String serviceId = serviceIdFor(serviceSpec);
final String actionId = serviceAction.getId();
final List<ObjectActionParameter> parameters = serviceAction.getParameters();
final Path path = new Path();
swagger.path(String.format("/services/%s/actions/%s/invoke", serviceId, actionId), path);
final String tag = tagFor(serviceId, "> services");
final Operation invokeOperation =
new Operation()
.tag(tag)
.description(
Util.roSpec("19.1") + ": (invoke) resource of " + serviceId + "#" + actionId)
.produces("application/json;profile=urn:org.apache.isis/v1")
.produces("application/json;profile=urn:org.apache.isis/v1;suppress=true")
.produces("application/json;profile=urn:org.restfulobjects:repr-types/action-result");
final ActionSemantics.Of semantics = serviceAction.getSemantics();
if (semantics.isSafeInNature()) {
path.get(invokeOperation);
for (final ObjectActionParameter parameter : parameters) {
invokeOperation.parameter(
new QueryParameter()
.name(parameter.getId())
.description(
Util.roSpec("2.9.1")
+ (!Strings.isNullOrEmpty(parameter.getDescription())
? (": " + parameter.getDescription())
: ""))
.required(false)
.type("string"));
}
if (!parameters.isEmpty()) {
invokeOperation.parameter(
new QueryParameter()
.name("x-isis-querystring")
.description(
Util.roSpec("2.10") + ": all (formal) arguments as base64 encoded string")
.required(false)
.type("string"));
}
} else {
if (semantics.isIdempotentInNature()) {
path.put(invokeOperation);
} else {
path.post(invokeOperation);
}
final ModelImpl bodyParam = new ModelImpl().type("object");
for (final ObjectActionParameter parameter : parameters) {
final Property valueProperty;
// TODO: need to switch on parameter's type and create appropriate impl of valueProperty
// if(parameter.getSpecification().isValue()) ...
valueProperty = stringProperty();
bodyParam.property(
parameter.getId(), new ObjectProperty().property("value", valueProperty));
}
invokeOperation
.consumes("application/json")
.parameter(new BodyParameter().name("body").schema(bodyParam));
}
invokeOperation.response(
200,
new Response()
.description(
serviceId
+ "#"
+ actionId
+ " , if Accept: application/json;profile=urn:org.apache.isis/v1")
.schema(actionReturnTypeFor(serviceAction)));
}
private Operation parseMethod(Method method) {
Operation operation = new Operation();
RequestMapping requestMapping = method.getAnnotation(RequestMapping.class);
Class<?> responseClass = null;
List<String> produces = new ArrayList<String>();
List<String> consumes = new ArrayList<String>();
String responseContainer = null;
String operationId = method.getName();
Map<String, Property> defaultResponseHeaders = null;
Set<Map<String, Object>> customExtensions = null;
ApiOperation apiOperation = method.getAnnotation(ApiOperation.class);
if (apiOperation.hidden()) return null;
if (!"".equals(apiOperation.nickname())) operationId = apiOperation.nickname();
defaultResponseHeaders = parseResponseHeaders(apiOperation.responseHeaders());
operation.summary(apiOperation.value()).description(apiOperation.notes());
customExtensions = parseCustomExtensions(apiOperation.extensions());
if (customExtensions != null) {
for (Map<String, Object> extension : customExtensions) {
if (extension != null) {
for (Map.Entry<String, Object> map : extension.entrySet()) {
operation.setVendorExtension(
map.getKey().startsWith("x-") ? map.getKey() : "x-" + map.getKey(), map.getValue());
}
}
}
}
if (apiOperation.response() != null && !Void.class.equals(apiOperation.response()))
responseClass = apiOperation.response();
if (!"".equals(apiOperation.responseContainer()))
responseContainer = apiOperation.responseContainer();
/// security
if (apiOperation.authorizations() != null) {
List<SecurityRequirement> securities = new ArrayList<SecurityRequirement>();
for (Authorization auth : apiOperation.authorizations()) {
if (auth.value() != null && !"".equals(auth.value())) {
SecurityRequirement security = new SecurityRequirement();
security.setName(auth.value());
AuthorizationScope[] scopes = auth.scopes();
for (AuthorizationScope scope : scopes) {
if (scope.scope() != null && !"".equals(scope.scope())) {
security.addScope(scope.scope());
}
}
securities.add(security);
}
}
if (securities.size() > 0) {
for (SecurityRequirement sec : securities) operation.security(sec);
}
}
if (responseClass == null) {
// pick out response from method declaration
LOG.info("picking up response class from method " + method);
Type t = method.getGenericReturnType();
responseClass = method.getReturnType();
if (responseClass.equals(ResponseEntity.class)) {
responseClass = getGenericSubtype(method.getReturnType(), method.getGenericReturnType());
}
if (!responseClass.equals(Void.class)
&& !"void".equals(responseClass.toString())
&& responseClass.getAnnotation(Api.class) == null) {
LOG.info("reading model " + responseClass);
Map<String, Model> models = ModelConverters.getInstance().readAll(t);
}
}
if (responseClass != null
&& !responseClass.equals(Void.class)
&& !responseClass.equals(ResponseEntity.class)
&& responseClass.getAnnotation(Api.class) == null) {
if (isPrimitive(responseClass)) {
Property responseProperty = null;
Property property = ModelConverters.getInstance().readAsProperty(responseClass);
if (property != null) {
if ("list".equalsIgnoreCase(responseContainer))
responseProperty = new ArrayProperty(property);
else if ("map".equalsIgnoreCase(responseContainer))
responseProperty = new MapProperty(property);
else responseProperty = property;
operation.response(
200,
new Response()
.description("successful operation")
.schema(responseProperty)
.headers(defaultResponseHeaders));
}
} else if (!responseClass.equals(Void.class) && !"void".equals(responseClass.toString())) {
Map<String, Model> models = ModelConverters.getInstance().read(responseClass);
if (models.size() == 0) {
Property pp = ModelConverters.getInstance().readAsProperty(responseClass);
operation.response(
200,
new Response()
.description("successful operation")
.schema(pp)
.headers(defaultResponseHeaders));
}
for (String key : models.keySet()) {
Property responseProperty = null;
if ("list".equalsIgnoreCase(responseContainer))
responseProperty = new ArrayProperty(new RefProperty().asDefault(key));
else if ("map".equalsIgnoreCase(responseContainer))
responseProperty = new MapProperty(new RefProperty().asDefault(key));
else responseProperty = new RefProperty().asDefault(key);
operation.response(
200,
new Response()
.description("successful operation")
.schema(responseProperty)
.headers(defaultResponseHeaders));
swagger.model(key, models.get(key));
}
models = ModelConverters.getInstance().readAll(responseClass);
for (String key : models.keySet()) {
swagger.model(key, models.get(key));
}
}
}
operation.operationId(operationId);
if (requestMapping.produces() != null) {
for (String str : Arrays.asList(requestMapping.produces())) {
if (!produces.contains(str)) {
produces.add(str);
}
}
}
if (requestMapping.consumes() != null) {
for (String str : Arrays.asList(requestMapping.consumes())) {
if (!consumes.contains(str)) {
consumes.add(str);
}
}
}
ApiResponses responseAnnotation = method.getAnnotation(ApiResponses.class);
if (responseAnnotation != null) {
updateApiResponse(operation, responseAnnotation);
} else {
ResponseStatus responseStatus = method.getAnnotation(ResponseStatus.class);
if (responseStatus != null) {
operation.response(
responseStatus.value().value(), new Response().description(responseStatus.reason()));
}
}
boolean isDeprecated = false;
Deprecated annotation = method.getAnnotation(Deprecated.class);
if (annotation != null) isDeprecated = true;
boolean hidden = false;
if (apiOperation != null) hidden = apiOperation.hidden();
// process parameters
Class[] parameterTypes = method.getParameterTypes();
Type[] genericParameterTypes = method.getGenericParameterTypes();
Annotation[][] paramAnnotations = method.getParameterAnnotations();
// paramTypes = method.getParameterTypes
// genericParamTypes = method.getGenericParameterTypes
for (int i = 0; i < parameterTypes.length; i++) {
Type type = genericParameterTypes[i];
List<Annotation> annotations = Arrays.asList(paramAnnotations[i]);
List<Parameter> parameters = getParameters(type, annotations);
for (Parameter parameter : parameters) {
operation.parameter(parameter);
}
}
if (operation.getResponses() == null) {
operation.defaultResponse(new Response().description("successful operation"));
}
// Process @ApiImplicitParams
this.readImplicitParameters(method, operation);
return operation;
}