You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@syncope.apache.org by il...@apache.org on 2019/11/18 07:45:01 UTC
[syncope] 02/02: Swagger docs improvements
This is an automated email from the ASF dual-hosted git repository.
ilgrosso pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/syncope.git
commit 44fead1548022bba9589d8136f2c4f8c2af83842
Author: Francesco Chicchiriccò <il...@apache.org>
AuthorDate: Mon Nov 18 08:38:41 2019 +0100
Swagger docs improvements
---
.../common/rest/api/beans/AbstractQuery.java | 8 ++++++++
.../syncope/common/rest/api/beans/AnyQuery.java | 21 +++++++++++++++++++--
.../syncope/common/rest/api/beans/TaskQuery.java | 17 +++++++++++++++--
.../common/rest/api/service/JAXRSService.java | 4 ++++
.../core/rest/cxf/SyncopeOpenApiCustomizer.java | 8 +++++++-
.../core/persistence/jpa/entity/user/JPAUser.java | 2 +-
.../java/data/AnyObjectDataBinderImpl.java | 6 +++---
.../provisioning/java/data/GroupDataBinderImpl.java | 6 ++----
.../common/rest/api/beans/UserRequestFormQuery.java | 7 ++++++-
.../common/rest/api/beans/UserRequestQuery.java | 7 ++++++-
.../common/rest/api/service/UserRequestService.java | 2 +-
11 files changed, 72 insertions(+), 16 deletions(-)
diff --git a/common/idrepo/rest-api/src/main/java/org/apache/syncope/common/rest/api/beans/AbstractQuery.java b/common/idrepo/rest-api/src/main/java/org/apache/syncope/common/rest/api/beans/AbstractQuery.java
index 771e560..892bf0d 100644
--- a/common/idrepo/rest-api/src/main/java/org/apache/syncope/common/rest/api/beans/AbstractQuery.java
+++ b/common/idrepo/rest-api/src/main/java/org/apache/syncope/common/rest/api/beans/AbstractQuery.java
@@ -18,6 +18,8 @@
*/
package org.apache.syncope.common.rest.api.beans;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.Schema;
import java.io.Serializable;
import javax.validation.constraints.Min;
import javax.ws.rs.DefaultValue;
@@ -70,6 +72,8 @@ public abstract class AbstractQuery implements Serializable {
private String orderBy;
+ @Parameter(name = JAXRSService.PARAM_PAGE, description = "page", schema =
+ @Schema(minimum = "1", implementation = Integer.class, defaultValue = "1"))
public Integer getPage() {
return page;
}
@@ -81,6 +85,8 @@ public abstract class AbstractQuery implements Serializable {
this.page = page;
}
+ @Parameter(name = JAXRSService.PARAM_SIZE, description = "items per page", schema =
+ @Schema(minimum = "1", implementation = Integer.class, defaultValue = "25"))
public Integer getSize() {
return size;
}
@@ -92,6 +98,8 @@ public abstract class AbstractQuery implements Serializable {
this.size = size;
}
+ @Parameter(name = JAXRSService.PARAM_ORDERBY, description = "sorting conditions", schema =
+ @Schema(implementation = String.class, example = "key DESC"))
public String getOrderBy() {
return orderBy;
}
diff --git a/common/idrepo/rest-api/src/main/java/org/apache/syncope/common/rest/api/beans/AnyQuery.java b/common/idrepo/rest-api/src/main/java/org/apache/syncope/common/rest/api/beans/AnyQuery.java
index 104efa7..1a9d772 100644
--- a/common/idrepo/rest-api/src/main/java/org/apache/syncope/common/rest/api/beans/AnyQuery.java
+++ b/common/idrepo/rest-api/src/main/java/org/apache/syncope/common/rest/api/beans/AnyQuery.java
@@ -18,6 +18,9 @@
*/
package org.apache.syncope.common.rest.api.beans;
+import io.swagger.v3.oas.annotations.ExternalDocumentation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.Schema;
import javax.ws.rs.DefaultValue;
import javax.ws.rs.QueryParam;
import org.apache.syncope.common.lib.SyncopeConstants;
@@ -59,16 +62,25 @@ public class AnyQuery extends AbstractQuery {
private String fiql;
+ @Parameter(name = JAXRSService.PARAM_REALM, description = "realms define a hierarchical security domain tree, "
+ + "primarily meant for containing Users, Groups and Any Objects", schema =
+ @Schema(implementation = String.class, defaultValue = SyncopeConstants.ROOT_REALM, externalDocs =
+ @ExternalDocumentation(description = "Apache Syncope Reference Guide",
+ url = "http://syncope.apache.org/docs/2.1/reference-guide.html#realms")))
public String getRealm() {
return realm;
}
@DefaultValue(SyncopeConstants.ROOT_REALM)
- @QueryParam("realm")
+ @QueryParam(JAXRSService.PARAM_REALM)
public void setRealm(final String realm) {
this.realm = realm;
}
+ @Parameter(name = JAXRSService.PARAM_DETAILS, description = "whether detailed information is to be included, "
+ + "if applicable, about virtual attributes, (dynamic) roles, privileges, relationships, "
+ + "(dynamic) memberships or linked accounts", schema =
+ @Schema(implementation = Boolean.class))
public Boolean getDetails() {
return Optional.ofNullable(details).orElse(Boolean.TRUE);
}
@@ -83,9 +95,14 @@ public class AnyQuery extends AbstractQuery {
return fiql;
}
+ @Parameter(name = JAXRSService.PARAM_FIQL, description = "Feed Item Query Language (FIQL, pronounced “fickle”) is "
+ + "a simple but flexible, URI-friendly syntax for expressing filters across the entries in a syndicated "
+ + "feed.", example = "username==rossini", schema =
+ @Schema(implementation = String.class, externalDocs =
+ @ExternalDocumentation(description = "Apache Syncope Reference Guide",
+ url = "http://syncope.apache.org/docs/2.1/reference-guide.html#search")))
@QueryParam(JAXRSService.PARAM_FIQL)
public void setFiql(final String fiql) {
this.fiql = fiql;
}
-
}
diff --git a/common/idrepo/rest-api/src/main/java/org/apache/syncope/common/rest/api/beans/TaskQuery.java b/common/idrepo/rest-api/src/main/java/org/apache/syncope/common/rest/api/beans/TaskQuery.java
index 6b57ac5..22e9e97 100644
--- a/common/idrepo/rest-api/src/main/java/org/apache/syncope/common/rest/api/beans/TaskQuery.java
+++ b/common/idrepo/rest-api/src/main/java/org/apache/syncope/common/rest/api/beans/TaskQuery.java
@@ -18,7 +18,8 @@
*/
package org.apache.syncope.common.rest.api.beans;
-import javax.validation.constraints.Min;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.Schema;
import javax.validation.constraints.NotNull;
import javax.ws.rs.DefaultValue;
import javax.ws.rs.PathParam;
@@ -93,6 +94,8 @@ public class TaskQuery extends AbstractQuery {
this.type = type;
}
+ @Parameter(name = JAXRSService.PARAM_RESOURCE, description = "resource key to match", schema =
+ @Schema(implementation = String.class, example = "resource-ldap"))
public String getResource() {
return resource;
}
@@ -102,6 +105,8 @@ public class TaskQuery extends AbstractQuery {
this.resource = resource;
}
+ @Parameter(name = JAXRSService.PARAM_NOTIFICATION, description = "notification key to match", schema =
+ @Schema(implementation = String.class, example = "4bf255f1-85a0-43d6-8988-128dad646f08"))
public String getNotification() {
return notification;
}
@@ -111,6 +116,8 @@ public class TaskQuery extends AbstractQuery {
this.notification = notification;
}
+ @Parameter(name = JAXRSService.PARAM_ANYTYPE_KIND, description = "entity type to match", schema =
+ @Schema(implementation = AnyTypeKind.class))
public AnyTypeKind getAnyTypeKind() {
return anyTypeKind;
}
@@ -120,16 +127,22 @@ public class TaskQuery extends AbstractQuery {
this.anyTypeKind = anyTypeKind;
}
+ @Parameter(name = JAXRSService.PARAM_ENTITY_KEY, description = "entity key to match", schema =
+ @Schema(implementation = String.class, example = "50592942-73ec-44c4-a377-e859524245e4"))
public String getEntityKey() {
return entityKey;
}
- @Min(1)
+ @Parameter(name = JAXRSService.PARAM_RESOURCE, description = " key", schema =
+ @Schema(implementation = String.class, example = "resource-ldap"))
@QueryParam(JAXRSService.PARAM_ENTITY_KEY)
public void setEntityKey(final String entityKey) {
this.entityKey = entityKey;
}
+ @Parameter(name = JAXRSService.PARAM_DETAILS, description = "whether detailed information about executions is to "
+ + "be included", schema =
+ @Schema(implementation = Boolean.class))
public Boolean getDetails() {
return Optional.ofNullable(details).orElse(Boolean.TRUE);
}
diff --git a/common/idrepo/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/JAXRSService.java b/common/idrepo/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/JAXRSService.java
index f613370..455e208 100644
--- a/common/idrepo/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/JAXRSService.java
+++ b/common/idrepo/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/JAXRSService.java
@@ -36,6 +36,10 @@ public interface JAXRSService {
String PARAM_ENTITY_KEY = "entityKey";
+ String PARAM_USER = "user";
+
+ String PARAM_REALM = "realm";
+
String PARAM_DETAILS = "details";
String PARAM_CONNID_PAGED_RESULTS_COOKIE = "connIdPagedResultsCookie";
diff --git a/core/idrepo/rest-cxf/src/main/java/org/apache/syncope/core/rest/cxf/SyncopeOpenApiCustomizer.java b/core/idrepo/rest-cxf/src/main/java/org/apache/syncope/core/rest/cxf/SyncopeOpenApiCustomizer.java
index c0ec487..aeca8c9 100644
--- a/core/idrepo/rest-cxf/src/main/java/org/apache/syncope/core/rest/cxf/SyncopeOpenApiCustomizer.java
+++ b/core/idrepo/rest-cxf/src/main/java/org/apache/syncope/core/rest/cxf/SyncopeOpenApiCustomizer.java
@@ -19,6 +19,7 @@
package org.apache.syncope.core.rest.cxf;
import io.swagger.v3.oas.integration.api.OpenAPIConfiguration;
+import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.Operation;
import io.swagger.v3.oas.models.headers.Header;
import io.swagger.v3.oas.models.media.ArraySchema;
@@ -123,8 +124,13 @@ public class SyncopeOpenApiCustomizer extends OpenApiCustomizer {
parameter.setName(RESTHeaders.DOMAIN);
parameter.setRequired(true);
+ ExternalDocumentation extDoc = new ExternalDocumentation();
+ extDoc.setDescription("Apache Syncope Reference Guide");
+ extDoc.setUrl("http://syncope.apache.org/docs/2.1/reference-guide.html#domains");
+
Schema<String> schema = new Schema<>();
- schema.setType("string");
+ schema.setDescription("Domains are built to facilitate multitenancy.");
+ schema.setExternalDocs(extDoc);
schema.setEnum(domains);
schema.setDefault(SyncopeConstants.MASTER_DOMAIN);
parameter.setSchema(schema);
diff --git a/core/persistence-jpa/src/main/java/org/apache/syncope/core/persistence/jpa/entity/user/JPAUser.java b/core/persistence-jpa/src/main/java/org/apache/syncope/core/persistence/jpa/entity/user/JPAUser.java
index 1a7e075..d1692ed 100644
--- a/core/persistence-jpa/src/main/java/org/apache/syncope/core/persistence/jpa/entity/user/JPAUser.java
+++ b/core/persistence-jpa/src/main/java/org/apache/syncope/core/persistence/jpa/entity/user/JPAUser.java
@@ -421,7 +421,7 @@ public class JPAUser
@Override
public boolean add(final AnyTypeClass auxClass) {
checkType(auxClass, JPAAnyTypeClass.class);
- return auxClasses.contains((JPAAnyTypeClass) auxClass) || this.auxClasses.add((JPAAnyTypeClass) auxClass);
+ return auxClasses.contains((JPAAnyTypeClass) auxClass) || auxClasses.add((JPAAnyTypeClass) auxClass);
}
@Override
diff --git a/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/data/AnyObjectDataBinderImpl.java b/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/data/AnyObjectDataBinderImpl.java
index 0c0c730..dd1ef88 100644
--- a/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/data/AnyObjectDataBinderImpl.java
+++ b/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/data/AnyObjectDataBinderImpl.java
@@ -96,10 +96,10 @@ public class AnyObjectDataBinderImpl extends AbstractAnyDataBinder implements An
anyObjectDAO.findAllResources(anyObject),
details);
- if (details) {
- // dynamic realms
- anyObjectTO.getDynRealms().addAll(anyObjectDAO.findDynRealms(anyObject.getKey()));
+ // dynamic realms
+ anyObjectTO.getDynRealms().addAll(anyObjectDAO.findDynRealms(anyObject.getKey()));
+ if (details) {
// relationships
anyObjectTO.getRelationships().addAll(
anyObjectDAO.findAllRelationships(anyObject).stream().
diff --git a/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/data/GroupDataBinderImpl.java b/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/data/GroupDataBinderImpl.java
index a5d5486..1473247 100644
--- a/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/data/GroupDataBinderImpl.java
+++ b/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/data/GroupDataBinderImpl.java
@@ -355,10 +355,8 @@ public class GroupDataBinderImpl extends AbstractAnyDataBinder implements GroupD
group.getResources(),
details);
- if (details) {
- // dynamic realms
- groupTO.getDynRealms().addAll(groupDAO.findDynRealms(group.getKey()));
- }
+ // dynamic realms
+ groupTO.getDynRealms().addAll(groupDAO.findDynRealms(group.getKey()));
// Static user and AnyType membership counts
groupTO.setStaticUserMembershipCount(groupDAO.countUMembers(group));
diff --git a/ext/flowable/rest-api/src/main/java/org/apache/syncope/common/rest/api/beans/UserRequestFormQuery.java b/ext/flowable/rest-api/src/main/java/org/apache/syncope/common/rest/api/beans/UserRequestFormQuery.java
index c4ac3a0..f5a507b 100644
--- a/ext/flowable/rest-api/src/main/java/org/apache/syncope/common/rest/api/beans/UserRequestFormQuery.java
+++ b/ext/flowable/rest-api/src/main/java/org/apache/syncope/common/rest/api/beans/UserRequestFormQuery.java
@@ -18,7 +18,10 @@
*/
package org.apache.syncope.common.rest.api.beans;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.Schema;
import javax.ws.rs.QueryParam;
+import org.apache.syncope.common.rest.api.service.JAXRSService;
public class UserRequestFormQuery extends AbstractQuery {
@@ -39,11 +42,13 @@ public class UserRequestFormQuery extends AbstractQuery {
private String user;
+ @Parameter(name = JAXRSService.PARAM_USER, description = "user to match either by key or username", schema =
+ @Schema(implementation = String.class, example = "50592942-73ec-44c4-a377-e859524245e4"))
public String getUser() {
return user;
}
- @QueryParam("user")
+ @QueryParam(JAXRSService.PARAM_USER)
public void setUser(final String user) {
this.user = user;
}
diff --git a/ext/flowable/rest-api/src/main/java/org/apache/syncope/common/rest/api/beans/UserRequestQuery.java b/ext/flowable/rest-api/src/main/java/org/apache/syncope/common/rest/api/beans/UserRequestQuery.java
index 3f53629..19e5b72 100644
--- a/ext/flowable/rest-api/src/main/java/org/apache/syncope/common/rest/api/beans/UserRequestQuery.java
+++ b/ext/flowable/rest-api/src/main/java/org/apache/syncope/common/rest/api/beans/UserRequestQuery.java
@@ -18,7 +18,10 @@
*/
package org.apache.syncope.common.rest.api.beans;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.Schema;
import javax.ws.rs.QueryParam;
+import org.apache.syncope.common.rest.api.service.JAXRSService;
public class UserRequestQuery extends AbstractQuery {
@@ -39,11 +42,13 @@ public class UserRequestQuery extends AbstractQuery {
private String user;
+ @Parameter(name = JAXRSService.PARAM_USER, description = "user to match either by key or username", schema =
+ @Schema(implementation = String.class, example = "50592942-73ec-44c4-a377-e859524245e4"))
public String getUser() {
return user;
}
- @QueryParam("user")
+ @QueryParam(JAXRSService.PARAM_USER)
public void setUser(final String user) {
this.user = user;
}
diff --git a/ext/flowable/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/UserRequestService.java b/ext/flowable/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/UserRequestService.java
index 5de65a5..b38cd61 100644
--- a/ext/flowable/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/UserRequestService.java
+++ b/ext/flowable/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/UserRequestService.java
@@ -74,7 +74,7 @@ public interface UserRequestService extends JAXRSService {
@Produces({ MediaType.APPLICATION_JSON, RESTHeaders.APPLICATION_YAML, MediaType.APPLICATION_XML })
UserRequest start(
@NotNull @PathParam("bpmnProcess") String bpmnProcess,
- @QueryParam("user") String user);
+ @QueryParam(JAXRSService.PARAM_USER) String user);
/**
* Cancel a running user request.