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 2018/02/15 16:03:52 UTC
[1/2] syncope git commit: [SYNCOPE-1274] Adding documentation for
request / response additional headers
Repository: syncope
Updated Branches:
refs/heads/master 08c1aa43b -> 49ca71d8c
http://git-wip-us.apache.org/repos/asf/syncope/blob/49ca71d8/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/UserService.java
----------------------------------------------------------------------
diff --git a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/UserService.java b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/UserService.java
index 1cddfdd..82f9a72 100644
--- a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/UserService.java
+++ b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/UserService.java
@@ -18,6 +18,13 @@
*/
package org.apache.syncope.common.rest.api.service;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.enums.ParameterIn;
+import io.swagger.v3.oas.annotations.headers.Header;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.security.SecurityRequirements;
import io.swagger.v3.oas.annotations.tags.Tag;
@@ -30,11 +37,16 @@ import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;
+import javax.ws.rs.core.HttpHeaders;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import org.apache.syncope.common.lib.patch.StatusPatch;
import org.apache.syncope.common.lib.patch.UserPatch;
+import org.apache.syncope.common.lib.to.PagedResult;
+import org.apache.syncope.common.lib.to.ProvisioningResult;
import org.apache.syncope.common.lib.to.UserTO;
+import org.apache.syncope.common.rest.api.RESTHeaders;
+import org.apache.syncope.common.rest.api.beans.AnyQuery;
/**
* REST operations for users.
@@ -46,14 +58,41 @@ import org.apache.syncope.common.lib.to.UserTO;
@Path("users")
public interface UserService extends AnyService<UserTO> {
+ @Override
+ UserTO read(String key);
+
+ @Override
+ PagedResult<UserTO> search(AnyQuery anyQuery);
+
/**
* Creates a new user.
*
* @param userTO user to be created
* @param storePassword whether password shall be stored internally
* @return Response object featuring Location header of created user as well as the user itself
- * enriched with propagation status information - ProvisioningResult as Entity
+ * enriched with propagation status information
*/
+ @Parameter(name = RESTHeaders.PREFER, in = ParameterIn.HEADER,
+ description = "Allows client to specify a preference for the result to be returned from the server",
+ allowEmptyValue = true, schema =
+ @Schema(defaultValue = "return-content", allowableValues = { "return-content", "return-no-content" }))
+ @ApiResponses(
+ @ApiResponse(responseCode = "201",
+ description = "User successfully created enriched with propagation status information, as Entity,"
+ + "or empty if 'Prefer: return-no-content' was specified",
+ content =
+ @Content(schema =
+ @Schema(implementation = ProvisioningResult.class)), headers = {
+ @Header(name = RESTHeaders.RESOURCE_KEY, schema =
+ @Schema(type = "string"),
+ description = "UUID generated for the user created")
+ , @Header(name = HttpHeaders.LOCATION, schema =
+ @Schema(type = "string"),
+ description = "URL of the user created")
+ , @Header(name = RESTHeaders.PREFERENCE_APPLIED, schema =
+ @Schema(type = "string"),
+ description = "Allows the server to inform the "
+ + "client about the fact that a specified preference was applied") }))
@POST
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@@ -66,8 +105,23 @@ public interface UserService extends AnyService<UserTO> {
*
* @param userPatch modification to be applied to user matching the provided key
* @return Response object featuring the updated user enriched with propagation status information
- * - ProvisioningResult as Entity
*/
+ @Parameter(name = RESTHeaders.PREFER, in = ParameterIn.HEADER,
+ description = "Allows client to specify a preference for the result to be returned from the server",
+ allowEmptyValue = true, schema =
+ @Schema(defaultValue = "return-content", allowableValues = { "return-content", "return-no-content" }))
+ @ApiResponses({
+ @ApiResponse(responseCode = "200",
+ description = "User successfully updated enriched with propagation status information, as Entity",
+ content =
+ @Content(schema =
+ @Schema(implementation = ProvisioningResult.class)))
+ , @ApiResponse(responseCode = "204",
+ description = "No content if 'Prefer: return-no-content' was specified", headers =
+ @Header(name = RESTHeaders.PREFERENCE_APPLIED, schema =
+ @Schema(type = "string"),
+ description = "Allows the server to inform the "
+ + "client about the fact that a specified preference was applied")) })
@PATCH
@Path("{key}")
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@@ -79,8 +133,23 @@ public interface UserService extends AnyService<UserTO> {
*
* @param userTO complete update
* @return Response object featuring the updated user enriched with propagation status information
- * - ProvisioningResult as Entity
*/
+ @Parameter(name = RESTHeaders.PREFER, in = ParameterIn.HEADER,
+ description = "Allows client to specify a preference for the result to be returned from the server",
+ allowEmptyValue = true, schema =
+ @Schema(defaultValue = "return-content", allowableValues = { "return-content", "return-no-content" }))
+ @ApiResponses({
+ @ApiResponse(responseCode = "200",
+ description = "User successfully updated enriched with propagation status information, as Entity",
+ content =
+ @Content(schema =
+ @Schema(implementation = ProvisioningResult.class)))
+ , @ApiResponse(responseCode = "204",
+ description = "No content if 'Prefer: return-no-content' was specified", headers =
+ @Header(name = RESTHeaders.PREFERENCE_APPLIED, schema =
+ @Schema(type = "string"),
+ description = "Allows the server to inform the "
+ + "client about the fact that a specified preference was applied")) })
@PUT
@Path("{key}")
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@@ -92,8 +161,23 @@ public interface UserService extends AnyService<UserTO> {
*
* @param statusPatch status update details
* @return Response object featuring the updated user enriched with propagation status information
- * - ProvisioningResult as Entity
*/
+ @Parameter(name = RESTHeaders.PREFER, in = ParameterIn.HEADER,
+ description = "Allows client to specify a preference for the result to be returned from the server",
+ allowEmptyValue = true, schema =
+ @Schema(defaultValue = "return-content", allowableValues = { "return-content", "return-no-content" }))
+ @ApiResponses({
+ @ApiResponse(responseCode = "200",
+ description = "User successfully updated enriched with propagation status information, as Entity",
+ content =
+ @Content(schema =
+ @Schema(implementation = ProvisioningResult.class)))
+ , @ApiResponse(responseCode = "204",
+ description = "No content if 'Prefer: return-no-content' was specified", headers =
+ @Header(name = RESTHeaders.PREFERENCE_APPLIED, schema =
+ @Schema(type = "string"),
+ description = "Allows the server to inform the "
+ + "client about the fact that a specified preference was applied")) })
@POST
@Path("{key}/status")
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
[2/2] syncope git commit: [SYNCOPE-1274] Adding documentation for
request / response additional headers
Posted by il...@apache.org.
[SYNCOPE-1274] Adding documentation for request / response additional headers
Project: http://git-wip-us.apache.org/repos/asf/syncope/repo
Commit: http://git-wip-us.apache.org/repos/asf/syncope/commit/49ca71d8
Tree: http://git-wip-us.apache.org/repos/asf/syncope/tree/49ca71d8
Diff: http://git-wip-us.apache.org/repos/asf/syncope/diff/49ca71d8
Branch: refs/heads/master
Commit: 49ca71d8c3d3d1d9c126aa9fc9808dac2b3b0d5b
Parents: 08c1aa4
Author: Francesco Chicchiriccò <il...@apache.org>
Authored: Thu Feb 15 12:32:36 2018 +0100
Committer: Francesco Chicchiriccò <il...@apache.org>
Committed: Thu Feb 15 17:03:36 2018 +0100
----------------------------------------------------------------------
.../syncope/common/rest/api/RESTHeaders.java | 2 +-
.../rest/api/service/AccessTokenService.java | 23 ++++
.../rest/api/service/AnyObjectService.java | 76 ++++++++++++-
.../common/rest/api/service/AnyService.java | 26 ++++-
.../rest/api/service/AnyTypeClassService.java | 15 +++
.../common/rest/api/service/AnyTypeService.java | 15 +++
.../rest/api/service/ConnectorService.java | 15 +++
.../common/rest/api/service/DomainService.java | 15 +++
.../rest/api/service/DynRealmService.java | 15 +++
.../common/rest/api/service/GroupService.java | 78 +++++++++++++-
.../rest/api/service/MailTemplateService.java | 15 +++
.../rest/api/service/NotificationService.java | 15 +++
.../common/rest/api/service/PolicyService.java | 15 +++
.../common/rest/api/service/RealmService.java | 67 +++++++++++-
.../api/service/RelationshipTypeService.java | 15 +++
.../common/rest/api/service/ReportService.java | 15 +++
.../rest/api/service/ReportTemplateService.java | 15 +++
.../rest/api/service/ResourceService.java | 15 +++
.../common/rest/api/service/RoleService.java | 15 +++
.../common/rest/api/service/SchemaService.java | 15 +++
.../api/service/SecurityQuestionService.java | 15 +++
.../common/rest/api/service/TaskService.java | 15 +++
.../rest/api/service/UserSelfService.java | 108 +++++++++++++++++--
.../common/rest/api/service/UserService.java | 92 +++++++++++++++-
24 files changed, 686 insertions(+), 26 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/syncope/blob/49ca71d8/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/RESTHeaders.java
----------------------------------------------------------------------
diff --git a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/RESTHeaders.java b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/RESTHeaders.java
index 2a61321..40cd8ba 100644
--- a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/RESTHeaders.java
+++ b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/RESTHeaders.java
@@ -66,7 +66,7 @@ public final class RESTHeaders {
public static final String PREFER = "Prefer";
/**
- * Allowd the server to inform the client about the fact that a specified preference was applied.
+ * Allows the server to inform the client about the fact that a specified preference was applied.
* <a href="http://msdn.microsoft.com/en-us/library/hh554623.aspx">More information</a>.
*
* @see Preference
http://git-wip-us.apache.org/repos/asf/syncope/blob/49ca71d8/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/AccessTokenService.java
----------------------------------------------------------------------
diff --git a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/AccessTokenService.java b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/AccessTokenService.java
index e60b08a..b9756b0 100644
--- a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/AccessTokenService.java
+++ b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/AccessTokenService.java
@@ -19,6 +19,10 @@
package org.apache.syncope.common.rest.api.service;
import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.headers.Header;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.tags.Tag;
import javax.ws.rs.BeanParam;
@@ -33,6 +37,7 @@ import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import org.apache.syncope.common.lib.to.AccessTokenTO;
import org.apache.syncope.common.lib.to.PagedResult;
+import org.apache.syncope.common.rest.api.RESTHeaders;
import org.apache.syncope.common.rest.api.beans.AccessTokenQuery;
/**
@@ -50,6 +55,15 @@ public interface AccessTokenService extends JAXRSService {
*/
@Operation(security = {
@SecurityRequirement(name = "BasicAuthentication") })
+ @ApiResponses(
+ @ApiResponse(responseCode = "204",
+ description = "JWT successfully generated", headers = {
+ @Header(name = RESTHeaders.TOKEN, schema =
+ @Schema(type = "string"),
+ description = "Generated JWT")
+ , @Header(name = RESTHeaders.TOKEN_EXPIRE, schema =
+ @Schema(type = "string"),
+ description = "Expiration of the generated JWT") }))
@POST
@Path("login")
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@@ -63,6 +77,15 @@ public interface AccessTokenService extends JAXRSService {
*/
@Operation(security = {
@SecurityRequirement(name = "Bearer") })
+ @ApiResponses(
+ @ApiResponse(responseCode = "204",
+ description = "JWT successfully refreshed", headers = {
+ @Header(name = RESTHeaders.TOKEN, schema =
+ @Schema(type = "string"),
+ description = "Generated JWT")
+ , @Header(name = RESTHeaders.TOKEN_EXPIRE, schema =
+ @Schema(type = "string"),
+ description = "Expiration of the refreshed JWT") }))
@POST
@Path("refresh")
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
http://git-wip-us.apache.org/repos/asf/syncope/blob/49ca71d8/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/AnyObjectService.java
----------------------------------------------------------------------
diff --git a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/AnyObjectService.java b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/AnyObjectService.java
index ab68778..a694adc 100644
--- a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/AnyObjectService.java
+++ b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/AnyObjectService.java
@@ -18,6 +18,13 @@
*/
package org.apache.syncope.common.rest.api.service;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.enums.ParameterIn;
+import io.swagger.v3.oas.annotations.headers.Header;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.security.SecurityRequirements;
import io.swagger.v3.oas.annotations.tags.Tag;
@@ -28,10 +35,15 @@ import javax.ws.rs.POST;
import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
+import javax.ws.rs.core.HttpHeaders;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import org.apache.syncope.common.lib.patch.AnyObjectPatch;
import org.apache.syncope.common.lib.to.AnyObjectTO;
+import org.apache.syncope.common.lib.to.PagedResult;
+import org.apache.syncope.common.lib.to.ProvisioningResult;
+import org.apache.syncope.common.rest.api.RESTHeaders;
+import org.apache.syncope.common.rest.api.beans.AnyQuery;
/**
* REST operations for anyObjects.
@@ -43,13 +55,41 @@ import org.apache.syncope.common.lib.to.AnyObjectTO;
@Path("anyObjects")
public interface AnyObjectService extends AnyService<AnyObjectTO> {
+ @Override
+ AnyObjectTO read(String key);
+
+ @Override
+ PagedResult<AnyObjectTO> search(AnyQuery anyQuery);
+
/**
* Creates a new any object.
*
* @param anyObjectTO any object to be created
* @return Response object featuring Location header of created any object as well as the any
- * object itself enriched with propagation status information - ProvisioningResult as Entity
+ * object itself enriched with propagation status information
*/
+ @Parameter(name = RESTHeaders.PREFER, in = ParameterIn.HEADER,
+ description = "Allows client to specify a preference for the result to be returned from the server",
+ allowEmptyValue = true, schema =
+ @Schema(defaultValue = "return-content", allowableValues = { "return-content", "return-no-content" }))
+ @ApiResponses(
+ @ApiResponse(responseCode = "201",
+ description =
+ "Any object successfully created enriched with propagation status information, as Entity,"
+ + "or empty if 'Prefer: return-no-content' was specified",
+ content =
+ @Content(schema =
+ @Schema(implementation = ProvisioningResult.class)), headers = {
+ @Header(name = RESTHeaders.RESOURCE_KEY, schema =
+ @Schema(type = "string"),
+ description = "UUID generated for the any object created")
+ , @Header(name = HttpHeaders.LOCATION, schema =
+ @Schema(type = "string"),
+ description = "URL of the any object created")
+ , @Header(name = RESTHeaders.PREFERENCE_APPLIED, schema =
+ @Schema(type = "string"),
+ description = "Allows the server to inform the "
+ + "client about the fact that a specified preference was applied") }))
@POST
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@@ -60,8 +100,23 @@ public interface AnyObjectService extends AnyService<AnyObjectTO> {
*
* @param anyObjectPatch modification to be applied to any object matching the provided key
* @return Response object featuring the updated any object enriched with propagation status information
- * - ProvisioningResult as Entity
*/
+ @Parameter(name = RESTHeaders.PREFER, in = ParameterIn.HEADER,
+ description = "Allows client to specify a preference for the result to be returned from the server",
+ allowEmptyValue = true, schema =
+ @Schema(defaultValue = "return-content", allowableValues = { "return-content", "return-no-content" }))
+ @ApiResponses({
+ @ApiResponse(responseCode = "200",
+ description = "Any object successfully updated enriched with propagation status information, as Entity",
+ content =
+ @Content(schema =
+ @Schema(implementation = ProvisioningResult.class)))
+ , @ApiResponse(responseCode = "204",
+ description = "No content if 'Prefer: return-no-content' was specified", headers =
+ @Header(name = RESTHeaders.PREFERENCE_APPLIED, schema =
+ @Schema(type = "string"),
+ description = "Allows the server to inform the "
+ + "client about the fact that a specified preference was applied")) })
@PATCH
@Path("{key}")
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@@ -73,8 +128,23 @@ public interface AnyObjectService extends AnyService<AnyObjectTO> {
*
* @param anyObjectTO complete update
* @return Response object featuring the updated any object enriched with propagation status information
- * - ProvisioningResult as Entity
*/
+ @Parameter(name = RESTHeaders.PREFER, in = ParameterIn.HEADER,
+ description = "Allows client to specify a preference for the result to be returned from the server",
+ allowEmptyValue = true, schema =
+ @Schema(defaultValue = "return-content", allowableValues = { "return-content", "return-no-content" }))
+ @ApiResponses({
+ @ApiResponse(responseCode = "200",
+ description = "Any object successfully updated enriched with propagation status information, as Entity",
+ content =
+ @Content(schema =
+ @Schema(implementation = ProvisioningResult.class)))
+ , @ApiResponse(responseCode = "204",
+ description = "No content if 'Prefer: return-no-content' was specified", headers =
+ @Header(name = RESTHeaders.PREFERENCE_APPLIED, schema =
+ @Schema(type = "string"),
+ description = "Allows the server to inform the "
+ + "client about the fact that a specified preference was applied")) })
@PUT
@Path("{key}")
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
http://git-wip-us.apache.org/repos/asf/syncope/blob/49ca71d8/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/AnyService.java
----------------------------------------------------------------------
diff --git a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/AnyService.java b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/AnyService.java
index 03f4666..5dcccb1 100644
--- a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/AnyService.java
+++ b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/AnyService.java
@@ -18,6 +18,13 @@
*/
package org.apache.syncope.common.rest.api.service;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.enums.ParameterIn;
+import io.swagger.v3.oas.annotations.headers.Header;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
import java.util.Set;
import javax.validation.constraints.NotNull;
import javax.ws.rs.BeanParam;
@@ -37,7 +44,9 @@ import org.apache.syncope.common.lib.to.AnyTO;
import org.apache.syncope.common.lib.to.AttrTO;
import org.apache.syncope.common.lib.to.BulkAction;
import org.apache.syncope.common.lib.to.PagedResult;
+import org.apache.syncope.common.lib.to.ProvisioningResult;
import org.apache.syncope.common.lib.types.SchemaType;
+import org.apache.syncope.common.rest.api.RESTHeaders;
import org.apache.syncope.common.rest.api.beans.AnyQuery;
public interface AnyService<TO extends AnyTO> extends JAXRSService {
@@ -138,8 +147,23 @@ public interface AnyService<TO extends AnyTO> extends JAXRSService {
*
* @param key any object key or name
* @return Response object featuring the deleted any object enriched with propagation status information
- * - ProvisioningResult as Entity
*/
+ @Parameter(name = RESTHeaders.PREFER, in = ParameterIn.HEADER,
+ description = "Allows client to specify a preference for the result to be returned from the server",
+ allowEmptyValue = true, schema =
+ @Schema(defaultValue = "return-content", allowableValues = { "return-content", "return-no-content" }))
+ @ApiResponses({
+ @ApiResponse(responseCode = "200",
+ description = "User, Group or Any Object successfully deleted enriched with propagation status "
+ + "information, as Entity", content =
+ @Content(schema =
+ @Schema(implementation = ProvisioningResult.class)))
+ , @ApiResponse(responseCode = "204",
+ description = "No content if 'Prefer: return-no-content' was specified", headers =
+ @Header(name = RESTHeaders.PREFERENCE_APPLIED, schema =
+ @Schema(type = "string"),
+ description = "Allows the server to inform the "
+ + "client about the fact that a specified preference was applied")) })
@DELETE
@Path("{key}")
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
http://git-wip-us.apache.org/repos/asf/syncope/blob/49ca71d8/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/AnyTypeClassService.java
----------------------------------------------------------------------
diff --git a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/AnyTypeClassService.java b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/AnyTypeClassService.java
index e026650..6eb97a1 100644
--- a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/AnyTypeClassService.java
+++ b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/AnyTypeClassService.java
@@ -18,6 +18,10 @@
*/
package org.apache.syncope.common.rest.api.service;
+import io.swagger.v3.oas.annotations.headers.Header;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.security.SecurityRequirements;
import io.swagger.v3.oas.annotations.tags.Tag;
@@ -31,9 +35,11 @@ import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
+import javax.ws.rs.core.HttpHeaders;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import org.apache.syncope.common.lib.to.AnyTypeClassTO;
+import org.apache.syncope.common.rest.api.RESTHeaders;
/**
* REST operations for any type classes.
@@ -71,6 +77,15 @@ public interface AnyTypeClassService extends JAXRSService {
* @param anyTypeClassTO anyTypeClass to be created
* @return Response object featuring Location header of created anyTypeClass
*/
+ @ApiResponses(
+ @ApiResponse(responseCode = "201",
+ description = "AnyTypeClass successfully created", headers = {
+ @Header(name = RESTHeaders.RESOURCE_KEY, schema =
+ @Schema(type = "string"),
+ description = "Key value for the entity created")
+ , @Header(name = HttpHeaders.LOCATION, schema =
+ @Schema(type = "string"),
+ description = "URL of the entity created") }))
@POST
@Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
http://git-wip-us.apache.org/repos/asf/syncope/blob/49ca71d8/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/AnyTypeService.java
----------------------------------------------------------------------
diff --git a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/AnyTypeService.java b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/AnyTypeService.java
index e9438d2..b193245 100644
--- a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/AnyTypeService.java
+++ b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/AnyTypeService.java
@@ -18,6 +18,10 @@
*/
package org.apache.syncope.common.rest.api.service;
+import io.swagger.v3.oas.annotations.headers.Header;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.security.SecurityRequirements;
import io.swagger.v3.oas.annotations.tags.Tag;
@@ -31,9 +35,11 @@ import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
+import javax.ws.rs.core.HttpHeaders;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import org.apache.syncope.common.lib.to.AnyTypeTO;
+import org.apache.syncope.common.rest.api.RESTHeaders;
/**
* REST operations for any types.
@@ -71,6 +77,15 @@ public interface AnyTypeService extends JAXRSService {
* @param anyTypeTO anyType to be created
* @return Response object featuring Location header of created anyType
*/
+ @ApiResponses(
+ @ApiResponse(responseCode = "201",
+ description = "AnyType successfully created", headers = {
+ @Header(name = RESTHeaders.RESOURCE_KEY, schema =
+ @Schema(type = "string"),
+ description = "Key value for the entity created")
+ , @Header(name = HttpHeaders.LOCATION, schema =
+ @Schema(type = "string"),
+ description = "URL of the entity created") }))
@POST
@Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
Response create(@NotNull AnyTypeTO anyTypeTO);
http://git-wip-us.apache.org/repos/asf/syncope/blob/49ca71d8/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/ConnectorService.java
----------------------------------------------------------------------
diff --git a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/ConnectorService.java b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/ConnectorService.java
index 64647c5..63a55fc 100644
--- a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/ConnectorService.java
+++ b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/ConnectorService.java
@@ -18,6 +18,10 @@
*/
package org.apache.syncope.common.rest.api.service;
+import io.swagger.v3.oas.annotations.headers.Header;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.security.SecurityRequirements;
import io.swagger.v3.oas.annotations.tags.Tag;
@@ -33,11 +37,13 @@ import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;
+import javax.ws.rs.core.HttpHeaders;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import org.apache.syncope.common.lib.to.ConnBundleTO;
import org.apache.syncope.common.lib.to.ConnIdObjectClassTO;
import org.apache.syncope.common.lib.to.ConnInstanceTO;
+import org.apache.syncope.common.rest.api.RESTHeaders;
/**
* REST operations for connector bundles and instances.
@@ -122,6 +128,15 @@ public interface ConnectorService extends JAXRSService {
* @param connInstanceTO connector instance to be created
* @return Response object featuring Location header of created connector instance
*/
+ @ApiResponses(
+ @ApiResponse(responseCode = "201",
+ description = "ConnInstance successfully created", headers = {
+ @Header(name = RESTHeaders.RESOURCE_KEY, schema =
+ @Schema(type = "string"),
+ description = "UUID generated for the entity created")
+ , @Header(name = HttpHeaders.LOCATION, schema =
+ @Schema(type = "string"),
+ description = "URL of the entity created") }))
@POST
@Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
http://git-wip-us.apache.org/repos/asf/syncope/blob/49ca71d8/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/DomainService.java
----------------------------------------------------------------------
diff --git a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/DomainService.java b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/DomainService.java
index d367810..a9945a5 100644
--- a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/DomainService.java
+++ b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/DomainService.java
@@ -18,6 +18,10 @@
*/
package org.apache.syncope.common.rest.api.service;
+import io.swagger.v3.oas.annotations.headers.Header;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.security.SecurityRequirements;
import io.swagger.v3.oas.annotations.tags.Tag;
@@ -31,9 +35,11 @@ import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
+import javax.ws.rs.core.HttpHeaders;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import org.apache.syncope.common.lib.to.DomainTO;
+import org.apache.syncope.common.rest.api.RESTHeaders;
/**
* REST operations for domains.
@@ -71,6 +77,15 @@ public interface DomainService extends JAXRSService {
* @param domainTO domain to be created
* @return Response object featuring Location header of created domain
*/
+ @ApiResponses(
+ @ApiResponse(responseCode = "201",
+ description = "Domain successfully created", headers = {
+ @Header(name = RESTHeaders.RESOURCE_KEY, schema =
+ @Schema(type = "string"),
+ description = "Key value for the entity created")
+ , @Header(name = HttpHeaders.LOCATION, schema =
+ @Schema(type = "string"),
+ description = "URL of the entity created") }))
@POST
@Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
http://git-wip-us.apache.org/repos/asf/syncope/blob/49ca71d8/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/DynRealmService.java
----------------------------------------------------------------------
diff --git a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/DynRealmService.java b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/DynRealmService.java
index c438d7e..69342e2 100644
--- a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/DynRealmService.java
+++ b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/DynRealmService.java
@@ -18,6 +18,10 @@
*/
package org.apache.syncope.common.rest.api.service;
+import io.swagger.v3.oas.annotations.headers.Header;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.security.SecurityRequirements;
import io.swagger.v3.oas.annotations.tags.Tag;
@@ -31,9 +35,11 @@ import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
+import javax.ws.rs.core.HttpHeaders;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import org.apache.syncope.common.lib.to.DynRealmTO;
+import org.apache.syncope.common.rest.api.RESTHeaders;
/**
* REST operations for dynamic realms.
@@ -71,6 +77,15 @@ public interface DynRealmService extends JAXRSService {
* @param dynDynRealmTO dynamic realm to be created
* @return Response object featuring Location header of created dynamic realm
*/
+ @ApiResponses(
+ @ApiResponse(responseCode = "201",
+ description = "DynRealm successfully created", headers = {
+ @Header(name = RESTHeaders.RESOURCE_KEY, schema =
+ @Schema(type = "string"),
+ description = "Key value for the entity created")
+ , @Header(name = HttpHeaders.LOCATION, schema =
+ @Schema(type = "string"),
+ description = "URL of the entity created") }))
@POST
@Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
http://git-wip-us.apache.org/repos/asf/syncope/blob/49ca71d8/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/GroupService.java
----------------------------------------------------------------------
diff --git a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/GroupService.java b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/GroupService.java
index c3f68e3..d999df3 100644
--- a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/GroupService.java
+++ b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/GroupService.java
@@ -18,6 +18,13 @@
*/
package org.apache.syncope.common.rest.api.service;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.enums.ParameterIn;
+import io.swagger.v3.oas.annotations.headers.Header;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.security.SecurityRequirements;
import io.swagger.v3.oas.annotations.tags.Tag;
@@ -31,12 +38,17 @@ import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
+import javax.ws.rs.core.HttpHeaders;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import org.apache.syncope.common.lib.patch.GroupPatch;
import org.apache.syncope.common.lib.to.ExecTO;
import org.apache.syncope.common.lib.to.GroupTO;
+import org.apache.syncope.common.lib.to.PagedResult;
+import org.apache.syncope.common.lib.to.ProvisioningResult;
import org.apache.syncope.common.lib.types.BulkMembersActionType;
+import org.apache.syncope.common.rest.api.RESTHeaders;
+import org.apache.syncope.common.rest.api.beans.AnyQuery;
/**
* REST operations for groups.
@@ -48,13 +60,40 @@ import org.apache.syncope.common.lib.types.BulkMembersActionType;
@Path("groups")
public interface GroupService extends AnyService<GroupTO> {
+ @Override
+ GroupTO read(String key);
+
+ @Override
+ PagedResult<GroupTO> search(AnyQuery anyQuery);
+
/**
* Creates a new group.
*
* @param groupTO group to be created
* @return Response object featuring Location header of created group as well as the any
- * object itself enriched with propagation status information - ProvisioningResult as Entity
+ * object itself enriched with propagation status information
*/
+ @Parameter(name = RESTHeaders.PREFER, in = ParameterIn.HEADER,
+ description = "Allows client to specify a preference for the result to be returned from the server",
+ allowEmptyValue = true, schema =
+ @Schema(defaultValue = "return-content", allowableValues = { "return-content", "return-no-content" }))
+ @ApiResponses(
+ @ApiResponse(responseCode = "201",
+ description = "Group successfully created enriched with propagation status information, as Entity,"
+ + "or empty if 'Prefer: return-no-content' was specified",
+ content =
+ @Content(schema =
+ @Schema(implementation = ProvisioningResult.class)), headers = {
+ @Header(name = RESTHeaders.RESOURCE_KEY, schema =
+ @Schema(type = "string"),
+ description = "UUID generated for the group created")
+ , @Header(name = HttpHeaders.LOCATION, schema =
+ @Schema(type = "string"),
+ description = "URL of the group created")
+ , @Header(name = RESTHeaders.PREFERENCE_APPLIED, schema =
+ @Schema(type = "string"),
+ description = "Allows the server to inform the "
+ + "client about the fact that a specified preference was applied") }))
@POST
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@@ -65,8 +104,23 @@ public interface GroupService extends AnyService<GroupTO> {
*
* @param groupPatch modification to be applied to group matching the provided key
* @return Response object featuring the updated group enriched with propagation status information
- * - ProvisioningResult as Entity
*/
+ @Parameter(name = RESTHeaders.PREFER, in = ParameterIn.HEADER,
+ description = "Allows client to specify a preference for the result to be returned from the server",
+ allowEmptyValue = true, schema =
+ @Schema(defaultValue = "return-content", allowableValues = { "return-content", "return-no-content" }))
+ @ApiResponses({
+ @ApiResponse(responseCode = "200",
+ description = "Group successfully updated enriched with propagation status information, as Entity",
+ content =
+ @Content(schema =
+ @Schema(implementation = ProvisioningResult.class)))
+ , @ApiResponse(responseCode = "204",
+ description = "No content if 'Prefer: return-no-content' was specified", headers =
+ @Header(name = RESTHeaders.PREFERENCE_APPLIED, schema =
+ @Schema(type = "string"),
+ description = "Allows the server to inform the "
+ + "client about the fact that a specified preference was applied")) })
@PATCH
@Path("{key}")
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@@ -78,8 +132,23 @@ public interface GroupService extends AnyService<GroupTO> {
*
* @param groupTO complete update
* @return Response object featuring the updated group enriched with propagation status information
- * - ProvisioningResult as Entity
*/
+ @Parameter(name = RESTHeaders.PREFER, in = ParameterIn.HEADER,
+ description = "Allows client to specify a preference for the result to be returned from the server",
+ allowEmptyValue = true, schema =
+ @Schema(defaultValue = "return-content", allowableValues = { "return-content", "return-no-content" }))
+ @ApiResponses({
+ @ApiResponse(responseCode = "200",
+ description = "Group successfully updated enriched with propagation status information, as Entity",
+ content =
+ @Content(schema =
+ @Schema(implementation = ProvisioningResult.class)))
+ , @ApiResponse(responseCode = "204",
+ description = "No content if 'Prefer: return-no-content' was specified", headers =
+ @Header(name = RESTHeaders.PREFERENCE_APPLIED, schema =
+ @Schema(type = "string"),
+ description = "Allows the server to inform the "
+ + "client about the fact that a specified preference was applied")) })
@PUT
@Path("{key}")
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@@ -87,8 +156,7 @@ public interface GroupService extends AnyService<GroupTO> {
Response update(@NotNull GroupTO groupTO);
/**
- * This method is similar to read() but uses different authentication handling to ensure that a group
- * can read his own groups.
+ * This method allows a user to read his own groups.
*
* @return own groups
*/
http://git-wip-us.apache.org/repos/asf/syncope/blob/49ca71d8/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/MailTemplateService.java
----------------------------------------------------------------------
diff --git a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/MailTemplateService.java b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/MailTemplateService.java
index 7abfa36..0e83a90 100644
--- a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/MailTemplateService.java
+++ b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/MailTemplateService.java
@@ -18,6 +18,10 @@
*/
package org.apache.syncope.common.rest.api.service;
+import io.swagger.v3.oas.annotations.headers.Header;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.security.SecurityRequirements;
import io.swagger.v3.oas.annotations.tags.Tag;
@@ -32,10 +36,12 @@ import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
+import javax.ws.rs.core.HttpHeaders;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import org.apache.syncope.common.lib.to.MailTemplateTO;
import org.apache.syncope.common.lib.types.MailTemplateFormat;
+import org.apache.syncope.common.rest.api.RESTHeaders;
/**
* REST operations for mail templates.
@@ -62,6 +68,15 @@ public interface MailTemplateService extends JAXRSService {
* @param mailTemplateTO Creates a new mail template.
* @return Response object featuring Location header of created mail template
*/
+ @ApiResponses(
+ @ApiResponse(responseCode = "201",
+ description = "MailTemplate successfully created", headers = {
+ @Header(name = RESTHeaders.RESOURCE_KEY, schema =
+ @Schema(type = "string"),
+ description = "Key value for the entity created")
+ , @Header(name = HttpHeaders.LOCATION, schema =
+ @Schema(type = "string"),
+ description = "URL of the entity created") }))
@POST
@Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
http://git-wip-us.apache.org/repos/asf/syncope/blob/49ca71d8/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/NotificationService.java
----------------------------------------------------------------------
diff --git a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/NotificationService.java b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/NotificationService.java
index 0c761b3..343a0c8 100644
--- a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/NotificationService.java
+++ b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/NotificationService.java
@@ -18,6 +18,10 @@
*/
package org.apache.syncope.common.rest.api.service;
+import io.swagger.v3.oas.annotations.headers.Header;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.security.SecurityRequirements;
import io.swagger.v3.oas.annotations.tags.Tag;
@@ -32,11 +36,13 @@ import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;
+import javax.ws.rs.core.HttpHeaders;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import org.apache.syncope.common.lib.to.JobTO;
import org.apache.syncope.common.lib.to.NotificationTO;
import org.apache.syncope.common.lib.types.JobAction;
+import org.apache.syncope.common.rest.api.RESTHeaders;
/**
* REST operations for notifications.
@@ -74,6 +80,15 @@ public interface NotificationService extends JAXRSService {
* @param notificationTO Creates a new notification.
* @return Response object featuring Location header of created notification
*/
+ @ApiResponses(
+ @ApiResponse(responseCode = "201",
+ description = "Notification successfully created", headers = {
+ @Header(name = RESTHeaders.RESOURCE_KEY, schema =
+ @Schema(type = "string"),
+ description = "UUID generated for the entity created")
+ , @Header(name = HttpHeaders.LOCATION, schema =
+ @Schema(type = "string"),
+ description = "URL of the entity created") }))
@POST
@Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
http://git-wip-us.apache.org/repos/asf/syncope/blob/49ca71d8/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/PolicyService.java
----------------------------------------------------------------------
diff --git a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/PolicyService.java b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/PolicyService.java
index 40e65ac..c2b7c33 100644
--- a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/PolicyService.java
+++ b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/PolicyService.java
@@ -18,6 +18,10 @@
*/
package org.apache.syncope.common.rest.api.service;
+import io.swagger.v3.oas.annotations.headers.Header;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.security.SecurityRequirements;
import io.swagger.v3.oas.annotations.tags.Tag;
@@ -31,10 +35,12 @@ import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
+import javax.ws.rs.core.HttpHeaders;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import org.apache.syncope.common.lib.policy.PolicyTO;
import org.apache.syncope.common.lib.types.PolicyType;
+import org.apache.syncope.common.rest.api.RESTHeaders;
/**
* REST operations for policies.
@@ -78,6 +84,15 @@ public interface PolicyService extends JAXRSService {
* @param policyTO Policy to be created (needs to match type)
* @return Response object featuring Location header of created policy
*/
+ @ApiResponses(
+ @ApiResponse(responseCode = "201",
+ description = "Policy successfully created", headers = {
+ @Header(name = RESTHeaders.RESOURCE_KEY, schema =
+ @Schema(type = "string"),
+ description = "UUID generated for the entity created")
+ , @Header(name = HttpHeaders.LOCATION, schema =
+ @Schema(type = "string"),
+ description = "URL of the entity created") }))
@POST
@Path("{type}")
@Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
http://git-wip-us.apache.org/repos/asf/syncope/blob/49ca71d8/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/RealmService.java
----------------------------------------------------------------------
diff --git a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/RealmService.java b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/RealmService.java
index 2909fc5..517aa20 100644
--- a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/RealmService.java
+++ b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/RealmService.java
@@ -18,6 +18,13 @@
*/
package org.apache.syncope.common.rest.api.service;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.enums.ParameterIn;
+import io.swagger.v3.oas.annotations.headers.Header;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.security.SecurityRequirements;
import io.swagger.v3.oas.annotations.tags.Tag;
@@ -31,9 +38,12 @@ import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
+import javax.ws.rs.core.HttpHeaders;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
+import org.apache.syncope.common.lib.to.ProvisioningResult;
import org.apache.syncope.common.lib.to.RealmTO;
+import org.apache.syncope.common.rest.api.RESTHeaders;
/**
* REST operations for realms.
@@ -71,8 +81,29 @@ public interface RealmService extends JAXRSService {
* @param parentPath full path of the parent realm
* @param realmTO new realm.
* @return Response object featuring Location header of created realm as well as the realm itself
- * enriched with propagation status information - ProvisioningResult as Entity
+ * enriched with propagation status information
*/
+ @Parameter(name = RESTHeaders.PREFER, in = ParameterIn.HEADER,
+ description = "Allows client to specify a preference for the result to be returned from the server",
+ allowEmptyValue = true, schema =
+ @Schema(defaultValue = "return-content", allowableValues = { "return-content", "return-no-content" }))
+ @ApiResponses(
+ @ApiResponse(responseCode = "201",
+ description = "Realm successfully created enriched with propagation status information, as Entity,"
+ + "or empty if 'Prefer: return-no-content' was specified",
+ content =
+ @Content(schema =
+ @Schema(implementation = ProvisioningResult.class)), headers = {
+ @Header(name = RESTHeaders.RESOURCE_KEY, schema =
+ @Schema(type = "string"),
+ description = "UUID generated for the realm created")
+ , @Header(name = HttpHeaders.LOCATION, schema =
+ @Schema(type = "string"),
+ description = "URL of the realm created")
+ , @Header(name = RESTHeaders.PREFERENCE_APPLIED, schema =
+ @Schema(type = "string"),
+ description = "Allows the server to inform the "
+ + "client about the fact that a specified preference was applied") }))
@POST
@Path("{parentPath:.*}")
@Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@@ -84,8 +115,23 @@ public interface RealmService extends JAXRSService {
*
* @param realmTO realm to be stored
* @return Response object featuring the updated realm enriched with propagation status information
- * - ProvisioningResult as Entity
*/
+ @Parameter(name = RESTHeaders.PREFER, in = ParameterIn.HEADER,
+ description = "Allows client to specify a preference for the result to be returned from the server",
+ allowEmptyValue = true, schema =
+ @Schema(defaultValue = "return-content", allowableValues = { "return-content", "return-no-content" }))
+ @ApiResponses({
+ @ApiResponse(responseCode = "200",
+ description = "Realm successfully updated enriched with propagation status information, as Entity",
+ content =
+ @Content(schema =
+ @Schema(implementation = ProvisioningResult.class)))
+ , @ApiResponse(responseCode = "204",
+ description = "No content if 'Prefer: return-no-content' was specified", headers =
+ @Header(name = RESTHeaders.PREFERENCE_APPLIED, schema =
+ @Schema(type = "string"),
+ description = "Allows the server to inform the "
+ + "client about the fact that a specified preference was applied")) })
@PUT
@Path("{fullPath:.*}")
@Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@@ -97,8 +143,23 @@ public interface RealmService extends JAXRSService {
*
* @param fullPath realm path
* @return Response object featuring the deleted realm enriched with propagation status information
- * - ProvisioningResult as Entity
*/
+ @Parameter(name = RESTHeaders.PREFER, in = ParameterIn.HEADER,
+ description = "Allows client to specify a preference for the result to be returned from the server",
+ allowEmptyValue = true, schema =
+ @Schema(defaultValue = "return-content", allowableValues = { "return-content", "return-no-content" }))
+ @ApiResponses({
+ @ApiResponse(responseCode = "200",
+ description = "Realm successfully deleted enriched with propagation status information, as Entity",
+ content =
+ @Content(schema =
+ @Schema(implementation = ProvisioningResult.class)))
+ , @ApiResponse(responseCode = "204",
+ description = "No content if 'Prefer: return-no-content' was specified", headers =
+ @Header(name = RESTHeaders.PREFERENCE_APPLIED, schema =
+ @Schema(type = "string"),
+ description = "Allows the server to inform the "
+ + "client about the fact that a specified preference was applied")) })
@DELETE
@Path("{fullPath:.*}")
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
http://git-wip-us.apache.org/repos/asf/syncope/blob/49ca71d8/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/RelationshipTypeService.java
----------------------------------------------------------------------
diff --git a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/RelationshipTypeService.java b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/RelationshipTypeService.java
index bd72582..a5f4987 100644
--- a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/RelationshipTypeService.java
+++ b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/RelationshipTypeService.java
@@ -18,6 +18,10 @@
*/
package org.apache.syncope.common.rest.api.service;
+import io.swagger.v3.oas.annotations.headers.Header;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.security.SecurityRequirements;
import io.swagger.v3.oas.annotations.tags.Tag;
@@ -31,9 +35,11 @@ import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
+import javax.ws.rs.core.HttpHeaders;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import org.apache.syncope.common.lib.to.RelationshipTypeTO;
+import org.apache.syncope.common.rest.api.RESTHeaders;
/**
* REST operations for relationship types.
@@ -71,6 +77,15 @@ public interface RelationshipTypeService extends JAXRSService {
* @param relationshipTypeTO relationshipType to be created
* @return Response object featuring Location header of created relationshipType
*/
+ @ApiResponses(
+ @ApiResponse(responseCode = "201",
+ description = "RelationshipType successfully created", headers = {
+ @Header(name = RESTHeaders.RESOURCE_KEY, schema =
+ @Schema(type = "string"),
+ description = "Key value for the entity created")
+ , @Header(name = HttpHeaders.LOCATION, schema =
+ @Schema(type = "string"),
+ description = "URL of the entity created") }))
@POST
@Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
http://git-wip-us.apache.org/repos/asf/syncope/blob/49ca71d8/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/ReportService.java
----------------------------------------------------------------------
diff --git a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/ReportService.java b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/ReportService.java
index 4431faa..2c5f3f1 100644
--- a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/ReportService.java
+++ b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/ReportService.java
@@ -18,6 +18,10 @@
*/
package org.apache.syncope.common.rest.api.service;
+import io.swagger.v3.oas.annotations.headers.Header;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.security.SecurityRequirements;
import io.swagger.v3.oas.annotations.tags.Tag;
@@ -32,10 +36,12 @@ import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;
+import javax.ws.rs.core.HttpHeaders;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import org.apache.syncope.common.lib.to.ReportTO;
import org.apache.syncope.common.lib.types.ReportExecExportFormat;
+import org.apache.syncope.common.rest.api.RESTHeaders;
/**
* REST operations for reports.
@@ -73,6 +79,15 @@ public interface ReportService extends ExecutableService {
* @param reportTO report to be created
* @return Response object featuring Location header of created report
*/
+ @ApiResponses(
+ @ApiResponse(responseCode = "201",
+ description = "Report successfully created", headers = {
+ @Header(name = RESTHeaders.RESOURCE_KEY, schema =
+ @Schema(type = "string"),
+ description = "UUID generated for the entity created")
+ , @Header(name = HttpHeaders.LOCATION, schema =
+ @Schema(type = "string"),
+ description = "URL of the entity created") }))
@POST
@Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
http://git-wip-us.apache.org/repos/asf/syncope/blob/49ca71d8/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/ReportTemplateService.java
----------------------------------------------------------------------
diff --git a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/ReportTemplateService.java b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/ReportTemplateService.java
index daf7e29..f85f133 100644
--- a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/ReportTemplateService.java
+++ b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/ReportTemplateService.java
@@ -18,6 +18,10 @@
*/
package org.apache.syncope.common.rest.api.service;
+import io.swagger.v3.oas.annotations.headers.Header;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.security.SecurityRequirements;
import io.swagger.v3.oas.annotations.tags.Tag;
@@ -32,10 +36,12 @@ import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
+import javax.ws.rs.core.HttpHeaders;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import org.apache.syncope.common.lib.to.ReportTemplateTO;
import org.apache.syncope.common.lib.types.ReportTemplateFormat;
+import org.apache.syncope.common.rest.api.RESTHeaders;
/**
* REST operations for report templates.
@@ -62,6 +68,15 @@ public interface ReportTemplateService extends JAXRSService {
* @param reportTemplateTO Creates a new report template.
* @return Response object featuring Location header of created report template
*/
+ @ApiResponses(
+ @ApiResponse(responseCode = "201",
+ description = "ReportTemplate successfully created", headers = {
+ @Header(name = RESTHeaders.RESOURCE_KEY, schema =
+ @Schema(type = "string"),
+ description = "Key value for the entity created")
+ , @Header(name = HttpHeaders.LOCATION, schema =
+ @Schema(type = "string"),
+ description = "URL of the entity created") }))
@POST
@Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
Response create(@NotNull ReportTemplateTO reportTemplateTO);
http://git-wip-us.apache.org/repos/asf/syncope/blob/49ca71d8/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/ResourceService.java
----------------------------------------------------------------------
diff --git a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/ResourceService.java b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/ResourceService.java
index caaf7ee..cc86628 100644
--- a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/ResourceService.java
+++ b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/ResourceService.java
@@ -18,6 +18,10 @@
*/
package org.apache.syncope.common.rest.api.service;
+import io.swagger.v3.oas.annotations.headers.Header;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.security.SecurityRequirements;
import io.swagger.v3.oas.annotations.tags.Tag;
@@ -32,6 +36,7 @@ import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
+import javax.ws.rs.core.HttpHeaders;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import org.apache.syncope.common.lib.patch.ResourceDeassociationPatch;
@@ -39,6 +44,7 @@ import org.apache.syncope.common.lib.to.BulkActionResult;
import org.apache.syncope.common.lib.to.ConnObjectTO;
import org.apache.syncope.common.lib.to.PagedConnObjectTOResult;
import org.apache.syncope.common.lib.to.ResourceTO;
+import org.apache.syncope.common.rest.api.RESTHeaders;
import org.apache.syncope.common.rest.api.beans.ConnObjectTOListQuery;
/**
@@ -110,6 +116,15 @@ public interface ResourceService extends JAXRSService {
* @param resourceTO Resource to be created
* @return Response object featuring Location header of created resource
*/
+ @ApiResponses(
+ @ApiResponse(responseCode = "201",
+ description = "Resource successfully created", headers = {
+ @Header(name = RESTHeaders.RESOURCE_KEY, schema =
+ @Schema(type = "string"),
+ description = "Key value for the entity created")
+ , @Header(name = HttpHeaders.LOCATION, schema =
+ @Schema(type = "string"),
+ description = "URL of the entity created") }))
@POST
@Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
http://git-wip-us.apache.org/repos/asf/syncope/blob/49ca71d8/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/RoleService.java
----------------------------------------------------------------------
diff --git a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/RoleService.java b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/RoleService.java
index 2ca9c5d..a3ead88 100644
--- a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/RoleService.java
+++ b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/RoleService.java
@@ -18,6 +18,10 @@
*/
package org.apache.syncope.common.rest.api.service;
+import io.swagger.v3.oas.annotations.headers.Header;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.security.SecurityRequirements;
import io.swagger.v3.oas.annotations.tags.Tag;
@@ -32,9 +36,11 @@ import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
+import javax.ws.rs.core.HttpHeaders;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import org.apache.syncope.common.lib.to.RoleTO;
+import org.apache.syncope.common.rest.api.RESTHeaders;
/**
* REST operations for roles.
@@ -72,6 +78,15 @@ public interface RoleService extends JAXRSService {
* @param roleTO role to be created
* @return Response object featuring Location header of created role
*/
+ @ApiResponses(
+ @ApiResponse(responseCode = "201",
+ description = "Role successfully created", headers = {
+ @Header(name = RESTHeaders.RESOURCE_KEY, schema =
+ @Schema(type = "string"),
+ description = "Key value for the entity created")
+ , @Header(name = HttpHeaders.LOCATION, schema =
+ @Schema(type = "string"),
+ description = "URL of the entity created") }))
@POST
@Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
http://git-wip-us.apache.org/repos/asf/syncope/blob/49ca71d8/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/SchemaService.java
----------------------------------------------------------------------
diff --git a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/SchemaService.java b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/SchemaService.java
index 69b06dc..dc832b3 100644
--- a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/SchemaService.java
+++ b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/SchemaService.java
@@ -18,6 +18,10 @@
*/
package org.apache.syncope.common.rest.api.service;
+import io.swagger.v3.oas.annotations.headers.Header;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.security.SecurityRequirements;
import io.swagger.v3.oas.annotations.tags.Tag;
@@ -32,10 +36,12 @@ import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
+import javax.ws.rs.core.HttpHeaders;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import org.apache.syncope.common.lib.to.SchemaTO;
import org.apache.syncope.common.lib.types.SchemaType;
+import org.apache.syncope.common.rest.api.RESTHeaders;
import org.apache.syncope.common.rest.api.beans.SchemaQuery;
/**
@@ -81,6 +87,15 @@ public interface SchemaService extends JAXRSService {
* @param schemaTO schema to be created
* @return Response object featuring Location header of created schema
*/
+ @ApiResponses(
+ @ApiResponse(responseCode = "201",
+ description = "Schema successfully created", headers = {
+ @Header(name = RESTHeaders.RESOURCE_KEY, schema =
+ @Schema(type = "string"),
+ description = "Key value for the entity created")
+ , @Header(name = HttpHeaders.LOCATION, schema =
+ @Schema(type = "string"),
+ description = "URL of the entity created") }))
@POST
@Path("{type}")
@Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
http://git-wip-us.apache.org/repos/asf/syncope/blob/49ca71d8/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/SecurityQuestionService.java
----------------------------------------------------------------------
diff --git a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/SecurityQuestionService.java b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/SecurityQuestionService.java
index eea01a5..2a2e0ab 100644
--- a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/SecurityQuestionService.java
+++ b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/SecurityQuestionService.java
@@ -18,6 +18,10 @@
*/
package org.apache.syncope.common.rest.api.service;
+import io.swagger.v3.oas.annotations.headers.Header;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.security.SecurityRequirements;
import io.swagger.v3.oas.annotations.tags.Tag;
@@ -31,9 +35,11 @@ import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
+import javax.ws.rs.core.HttpHeaders;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import org.apache.syncope.common.lib.to.SecurityQuestionTO;
+import org.apache.syncope.common.rest.api.RESTHeaders;
/**
* REST operations for configuration.
@@ -71,6 +77,15 @@ public interface SecurityQuestionService extends JAXRSService {
* @param securityQuestionTO security question to be created
* @return Response object featuring Location header of created security question
*/
+ @ApiResponses(
+ @ApiResponse(responseCode = "201",
+ description = "SecurityQuestion successfully created", headers = {
+ @Header(name = RESTHeaders.RESOURCE_KEY, schema =
+ @Schema(type = "string"),
+ description = "UUID generated for the entity created")
+ , @Header(name = HttpHeaders.LOCATION, schema =
+ @Schema(type = "string"),
+ description = "URL of the entity created") }))
@POST
@Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
http://git-wip-us.apache.org/repos/asf/syncope/blob/49ca71d8/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/TaskService.java
----------------------------------------------------------------------
diff --git a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/TaskService.java b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/TaskService.java
index c46dec0..60abb51 100644
--- a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/TaskService.java
+++ b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/TaskService.java
@@ -18,6 +18,10 @@
*/
package org.apache.syncope.common.rest.api.service;
+import io.swagger.v3.oas.annotations.headers.Header;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.security.SecurityRequirements;
import io.swagger.v3.oas.annotations.tags.Tag;
@@ -33,6 +37,7 @@ import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;
+import javax.ws.rs.core.HttpHeaders;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import org.apache.syncope.common.lib.to.TaskTO;
@@ -41,6 +46,7 @@ import org.apache.syncope.common.lib.to.BulkActionResult;
import org.apache.syncope.common.lib.to.PagedResult;
import org.apache.syncope.common.lib.to.SchedTaskTO;
import org.apache.syncope.common.lib.types.TaskType;
+import org.apache.syncope.common.rest.api.RESTHeaders;
import org.apache.syncope.common.rest.api.beans.TaskQuery;
/**
@@ -89,6 +95,15 @@ public interface TaskService extends ExecutableService {
* @param taskTO task to be created
* @return Response object featuring Location header of created task
*/
+ @ApiResponses(
+ @ApiResponse(responseCode = "201",
+ description = "Task successfully created", headers = {
+ @Header(name = RESTHeaders.RESOURCE_KEY, schema =
+ @Schema(type = "string"),
+ description = "UUID generated for the entity created")
+ , @Header(name = HttpHeaders.LOCATION, schema =
+ @Schema(type = "string"),
+ description = "URL of the entity created") }))
@POST
@Path("{type}")
@Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
http://git-wip-us.apache.org/repos/asf/syncope/blob/49ca71d8/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/UserSelfService.java
----------------------------------------------------------------------
diff --git a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/UserSelfService.java b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/UserSelfService.java
index d25be67..6ba8fd3 100644
--- a/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/UserSelfService.java
+++ b/common/rest-api/src/main/java/org/apache/syncope/common/rest/api/service/UserSelfService.java
@@ -19,6 +19,13 @@
package org.apache.syncope.common.rest.api.service;
import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.enums.ParameterIn;
+import io.swagger.v3.oas.annotations.headers.Header;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.tags.Tag;
import javax.validation.constraints.NotNull;
@@ -32,11 +39,14 @@ import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;
+import javax.ws.rs.core.HttpHeaders;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import org.apache.syncope.common.lib.patch.StatusPatch;
import org.apache.syncope.common.lib.patch.UserPatch;
+import org.apache.syncope.common.lib.to.ProvisioningResult;
import org.apache.syncope.common.lib.to.UserTO;
+import org.apache.syncope.common.rest.api.RESTHeaders;
/**
* REST operations for user self-management.
@@ -48,12 +58,24 @@ public interface UserSelfService extends JAXRSService {
/**
* Returns the user making the service call.
*
- * @return calling user data, including owned entitlements as header value
- * {@link org.apache.syncope.common.rest.api.RESTHeaders#OWNED_ENTITLEMENTS}
+ * @return calling user data, including own UUID and entitlements
*/
@Operation(security = {
@SecurityRequirement(name = "BasicAuthentication")
, @SecurityRequirement(name = "Bearer") })
+ @ApiResponses(
+ @ApiResponse(responseCode = "200", description = "Calling user data, including own UUID and entitlements",
+ content =
+ @Content(schema =
+ @Schema(implementation = UserTO.class)), headers = {
+ @Header(name = RESTHeaders.RESOURCE_KEY, schema =
+ @Schema(type = "string"),
+ description = "UUID of the calling user")
+ ,
+ @Header(name = RESTHeaders.OWNED_ENTITLEMENTS, schema =
+ @Schema(type = "string"),
+ description = "List of entitlements owned by the calling user")
+ }))
@GET
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
Response read();
@@ -63,9 +85,30 @@ public interface UserSelfService extends JAXRSService {
*
* @param userTO user to be created
* @param storePassword whether password shall be stored internally
- * @return Response object featuring Location header of self-registered user as well as the user
- * itself - ProvisioningResult as Entity
+ * @return Response object featuring Location header of self-registered user as well as the user itself
+ * enriched with propagation status information
*/
+ @Parameter(name = RESTHeaders.PREFER, in = ParameterIn.HEADER,
+ description = "Allows client to specify a preference for the result to be returned from the server",
+ allowEmptyValue = true, schema =
+ @Schema(defaultValue = "return-content", allowableValues = { "return-content", "return-no-content" }))
+ @ApiResponses(
+ @ApiResponse(responseCode = "201",
+ description = "User successfully created enriched with propagation status information, as Entity,"
+ + "or empty if 'Prefer: return-no-content' was specified",
+ content =
+ @Content(schema =
+ @Schema(implementation = ProvisioningResult.class)), headers = {
+ @Header(name = RESTHeaders.RESOURCE_KEY, schema =
+ @Schema(type = "string"),
+ description = "UUID generated for the user created")
+ , @Header(name = HttpHeaders.LOCATION, schema =
+ @Schema(type = "string"),
+ description = "URL of the user created")
+ , @Header(name = RESTHeaders.PREFERENCE_APPLIED, schema =
+ @Schema(type = "string"),
+ description = "Allows the server to inform the "
+ + "client about the fact that a specified preference was applied") }))
@POST
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@@ -76,11 +119,27 @@ public interface UserSelfService extends JAXRSService {
* Self-updates user.
*
* @param patch modification to be applied to self
- * @return Response object featuring the updated user - ProvisioningResult as Entity
+ * @return Response object featuring the updated user
*/
@Operation(security = {
@SecurityRequirement(name = "BasicAuthentication")
, @SecurityRequirement(name = "Bearer") })
+ @Parameter(name = RESTHeaders.PREFER, in = ParameterIn.HEADER,
+ description = "Allows client to specify a preference for the result to be returned from the server",
+ allowEmptyValue = true, schema =
+ @Schema(defaultValue = "return-content", allowableValues = { "return-content", "return-no-content" }))
+ @ApiResponses({
+ @ApiResponse(responseCode = "200",
+ description = "User successfully updated enriched with propagation status information, as Entity",
+ content =
+ @Content(schema =
+ @Schema(implementation = ProvisioningResult.class)))
+ , @ApiResponse(responseCode = "204",
+ description = "No content if 'Prefer: return-no-content' was specified", headers =
+ @Header(name = RESTHeaders.PREFERENCE_APPLIED, schema =
+ @Schema(type = "string"),
+ description = "Allows the server to inform the "
+ + "client about the fact that a specified preference was applied")) })
@PATCH
@Path("{key}")
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@@ -91,11 +150,27 @@ public interface UserSelfService extends JAXRSService {
* Self-updates user.
*
* @param user complete update
- * @return Response object featuring the updated user - ProvisioningResult as Entity
+ * @return Response object featuring the updated user
*/
@Operation(security = {
@SecurityRequirement(name = "BasicAuthentication")
, @SecurityRequirement(name = "Bearer") })
+ @Parameter(name = RESTHeaders.PREFER, in = ParameterIn.HEADER,
+ description = "Allows client to specify a preference for the result to be returned from the server",
+ allowEmptyValue = true, schema =
+ @Schema(defaultValue = "return-content", allowableValues = { "return-content", "return-no-content" }))
+ @ApiResponses({
+ @ApiResponse(responseCode = "200",
+ description = "User successfully updated enriched with propagation status information, as Entity",
+ content =
+ @Content(schema =
+ @Schema(implementation = ProvisioningResult.class)))
+ , @ApiResponse(responseCode = "204",
+ description = "No content if 'Prefer: return-no-content' was specified", headers =
+ @Header(name = RESTHeaders.PREFERENCE_APPLIED, schema =
+ @Schema(type = "string"),
+ description = "Allows the server to inform the "
+ + "client about the fact that a specified preference was applied")) })
@PUT
@Path("{key}")
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@@ -107,11 +182,26 @@ public interface UserSelfService extends JAXRSService {
*
* @param statusPatch status update details
* @return Response object featuring the updated user enriched with propagation status information
- * - ProvisioningResult as Entity
*/
@Operation(security = {
@SecurityRequirement(name = "BasicAuthentication")
, @SecurityRequirement(name = "Bearer") })
+ @Parameter(name = RESTHeaders.PREFER, in = ParameterIn.HEADER,
+ description = "Allows client to specify a preference for the result to be returned from the server",
+ allowEmptyValue = true, schema =
+ @Schema(defaultValue = "return-content", allowableValues = { "return-content", "return-no-content" }))
+ @ApiResponses({
+ @ApiResponse(responseCode = "200",
+ description = "User successfully updated enriched with propagation status information, as Entity",
+ content =
+ @Content(schema =
+ @Schema(implementation = ProvisioningResult.class)))
+ , @ApiResponse(responseCode = "204",
+ description = "No content if 'Prefer: return-no-content' was specified", headers =
+ @Header(name = RESTHeaders.PREFERENCE_APPLIED, schema =
+ @Schema(type = "string"),
+ description = "Allows the server to inform the "
+ + "client about the fact that a specified preference was applied")) })
@POST
@Path("{key}/status")
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@@ -121,7 +211,7 @@ public interface UserSelfService extends JAXRSService {
/**
* Self-deletes user.
*
- * @return Response object featuring the deleted user - ProvisioningResult as Entity
+ * @return Response object featuring the deleted user
*/
@Operation(security = {
@SecurityRequirement(name = "BasicAuthentication")
@@ -135,7 +225,7 @@ public interface UserSelfService extends JAXRSService {
*
* @param password the password value to update
*
- * @return Response object featuring the updated user - ProvisioningResult as Entity
+ * @return Response object featuring the updated user
*/
@Operation(security = {
@SecurityRequirement(name = "BasicAuthentication")