From bc297e8b341043bba6dc51beeb257a5d830961db Mon Sep 17 00:00:00 2001
From: Moritzjenny <moritzjenny@hotmail.com>
Date: Thu, 12 Sep 2019 17:39:58 +0200
Subject: [PATCH] OO-4096: add all annotations from previous documentation
---
.../group/LearningGroupWebService.java | 94 +++++++++-
.../olat/restapi/group/MyGroupWebService.java | 31 ++++
.../restapi/repository/CatalogWebService.java | 104 +++++++++++
.../RepositoryEntriesWebService.java | 21 ++-
.../RepositoryEntryLifecycleWebService.java | 12 ++
.../repository/RepositoryEntryWebService.java | 164 ++++++++++++++++++
.../course/CourseGroupWebService.java | 1 +
.../repository/course/CourseWebService.java | 80 +++++++++
.../restapi/system/DatabaseWebService.java | 13 ++
.../restapi/system/IndexerWebService.java | 25 +++
.../olat/restapi/system/MemoryWebService.java | 28 +++
.../restapi/system/MonitoringWebService.java | 14 ++
.../system/OpenOLATStatisticsWebService.java | 42 +++++
.../restapi/system/RuntimeWebService.java | 35 ++++
.../olat/restapi/system/StatusWebservice.java | 13 ++
.../olat/restapi/system/SystemWebService.java | 35 ++++
...IdentityToIdentityRelationsWebService.java | 35 ++++
.../restapi/OrganisationTypesWebService.java | 61 +++++++
.../user/restapi/OrganisationsWebService.java | 78 ++++++++-
.../user/restapi/RelationRolesWebService.java | 42 +++++
.../restapi/UserAuthenticationWebService.java | 37 ++++
.../user/restapi/UserCoursesWebService.java | 26 +++
.../user/restapi/UserFoldersWebService.java | 29 ++++
.../org/olat/user/restapi/UserWebService.java | 145 ++++++++++++++++
24 files changed, 1160 insertions(+), 5 deletions(-)
diff --git a/src/main/java/org/olat/restapi/group/LearningGroupWebService.java b/src/main/java/org/olat/restapi/group/LearningGroupWebService.java
index 1514d821809..5ec58b093e1 100644
--- a/src/main/java/org/olat/restapi/group/LearningGroupWebService.java
+++ b/src/main/java/org/olat/restapi/group/LearningGroupWebService.java
@@ -146,7 +146,7 @@ public class LearningGroupWebService {
@Operation(summary = "Return the list of all groups ", description = "Return the list of all groups if you have group manager permission, or all\n" +
" learning group that you particip with or owne")
@ApiResponses({
- @ApiResponse(responseCode = "200", description = "Array of results for the whole the course", content = {
+ @ApiResponse(responseCode = "200", description = "This is the list of all groups in OLAT system", content = {
@Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = GroupVO.class))),
@Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = GroupVO.class))) })})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
@@ -188,6 +188,11 @@ public class LearningGroupWebService {
*/
@GET
@Path("{groupKey}")
+ @Operation(summary = "Return the group specified by the key of the group", description = "RReturn the group specified by the key of the group")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "A business group in the OLAT system", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = GroupVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = GroupVO.class)) })})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response findById(@PathParam("groupKey") Long groupKey, @Context Request request,
@Context HttpServletRequest httpRequest) {
@@ -228,6 +233,13 @@ public class LearningGroupWebService {
* @return
*/
@PUT
+ @Operation(summary = "Create a group", description = "Create a group")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The saved business group", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = GroupVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = GroupVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The business group cannot be found") })
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response createGroup(final GroupVO group, @Context HttpServletRequest request) {
@@ -273,6 +285,13 @@ public class LearningGroupWebService {
*/
@POST
@Path("{groupKey}")
+ @Operation(summary = "Update a group", description = "Update a group")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The saved business group", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = GroupVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = GroupVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The business group cannot be found") })
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response postGroup(@PathParam("groupKey") Long groupKey, final GroupVO group, @Context HttpServletRequest request) {
@@ -308,6 +327,13 @@ public class LearningGroupWebService {
*/
@GET
@Path("{groupKey}/news")
+ @Operation(summary = "Returns the news", description = "Returns the news")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The news", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = String.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = String.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The business group cannot be found or the news tool is not enabled") })
@Produces({MediaType.TEXT_PLAIN})
public Response getNews(@PathParam("groupKey") Long groupKey, @Context HttpServletRequest request) {
BusinessGroupService bgs = CoreSpringFactory.getImpl(BusinessGroupService.class);
@@ -347,6 +373,13 @@ public class LearningGroupWebService {
*/
@POST
@Path("{groupKey}/news")
+ @Operation(summary = "Update the news", description = "Update the news")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The updated news", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = String.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = String.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The business group cannot be found or the news tool is not enabled") })
@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
public Response postNews(@PathParam("groupKey") Long groupKey, @FormParam("news") String news, @Context HttpServletRequest request) {
BusinessGroup bg = CoreSpringFactory.getImpl(BusinessGroupService.class).loadBusinessGroup(groupKey);
@@ -377,6 +410,11 @@ public class LearningGroupWebService {
*/
@DELETE
@Path("{groupKey}/news")
+ @Operation(summary = "Deletes the news of the group if the news tool is enabled", description = "Deletes the news of the group if the news tool is enabled")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The new are deleted"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The business group cannot be found or the news tool is not enabled") })
public Response deleteNews(@PathParam("groupKey") Long groupKey, @Context HttpServletRequest request) {
BusinessGroup bg = CoreSpringFactory.getImpl(BusinessGroupService.class).loadBusinessGroup(groupKey);
if(bg == null) {
@@ -480,6 +518,11 @@ public class LearningGroupWebService {
*/
@DELETE
@Path("{groupKey}")
+ @Operation(summary = "Deletes the business group specified by the groupKey", description = "Deletes the business group specified by the groupKey")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The business group is deleted"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The business group cannot be found or the news tool is not enabled") })
public Response deleteGroup(@PathParam("groupKey") Long groupKey, @Context HttpServletRequest request) {
if(!isGroupManager(request)) {
return Response.serverError().status(Status.UNAUTHORIZED).build();
@@ -507,6 +550,12 @@ public class LearningGroupWebService {
*/
@GET
@Path("{groupKey}/infos")
+ @Operation(summary = " Returns the informations of the group specified by the groupKey", description = " Returns the informations of the group specified by the groupKey")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The updated news", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = GroupInfoVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = GroupInfoVO.class)) }),
+ @ApiResponse(responseCode = "404", description = "The business group cannot be found") })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getInformations(@PathParam("groupKey") Long groupKey, @Context HttpServletRequest request) {
BusinessGroupService bgs = CoreSpringFactory.getImpl(BusinessGroupService.class);
@@ -533,7 +582,7 @@ public class LearningGroupWebService {
* @return
*/
@Path("{groupKey}/forum")
-
+ @Operation(summary = "Return the Forum web service", description = "Return the Forum web service")
public ForumWebService getForum(@PathParam("groupKey") Long groupKey, @Context HttpServletRequest request) {
BusinessGroupService bgs = CoreSpringFactory.getImpl(BusinessGroupService.class);
BusinessGroup bg = CoreSpringFactory.getImpl(BusinessGroupService.class).loadBusinessGroup(groupKey);
@@ -559,6 +608,7 @@ public class LearningGroupWebService {
}
@Path("{groupKey}/folder")
+ @Operation(summary = "Return the folder", description = "Return the folder")
public VFSWebservice getFolder(@PathParam("groupKey") Long groupKey, @Context HttpServletRequest request) {
BusinessGroupService bgs = CoreSpringFactory.getImpl(BusinessGroupService.class);
BusinessGroup bg = bgs.loadBusinessGroup(groupKey);
@@ -600,6 +650,7 @@ public class LearningGroupWebService {
* @return
*/
@Path("{groupKey}/wiki")
+ @Operation(summary = "Return the Forum web service", description = "Return the Forum web service")
public GroupWikiWebService getWiki(@PathParam("groupKey") Long groupKey, @Context HttpServletRequest request) {
BusinessGroupService bgs = CoreSpringFactory.getImpl(BusinessGroupService.class);
BusinessGroup bg = bgs.loadBusinessGroup(groupKey);
@@ -628,6 +679,7 @@ public class LearningGroupWebService {
* @return
*/
@Path("{groupKey}/calendar")
+ @Operation(summary = "Return the calendar web service", description = "Return the calendar web service")
public CalWebService getCalendarWebService(@PathParam("groupKey") Long groupKey, @Context HttpServletRequest request) {
CalendarModule calendarModule = CoreSpringFactory.getImpl(CalendarModule.class);
if(!calendarModule.isEnabled() || !calendarModule.isEnableGroupCalendar()) {
@@ -671,6 +723,13 @@ public class LearningGroupWebService {
*/
@GET
@Path("{groupKey}/owners")
+ @Operation(summary = "Returns the list of owners of the group specified by the groupKey", description = "Returns the list of owners of the group specified by the groupKey")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "Owners of the business group", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = UserVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = UserVO.class))) }),
+ @ApiResponse(responseCode = "404", description = "The business group cannot be found")
+ })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getTutors(@PathParam("groupKey") Long groupKey, @Context HttpServletRequest request) {
BusinessGroupService bgs = CoreSpringFactory.getImpl(BusinessGroupService.class);
@@ -707,6 +766,13 @@ public class LearningGroupWebService {
*/
@GET
@Path("{groupKey}/participants")
+ @Operation(summary = "Returns the list of participants of the group specified by the groupKey", description = "Returns the list of participants of the group specified by the groupKey")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "Participants of the business group", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = UserVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = UserVO.class))) }),
+ @ApiResponse(responseCode = "404", description = "The business group cannot be found")
+ })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getParticipants(@PathParam("groupKey") Long groupKey, @Context HttpServletRequest request) {
BusinessGroupService bgs = CoreSpringFactory.getImpl(BusinessGroupService.class);
@@ -751,6 +817,12 @@ public class LearningGroupWebService {
*/
@PUT
@Path("{groupKey}/owners/{identityKey}")
+ @Operation(summary = "Add an owner to the group", description = "Adds an owner to the group")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The user is added as owner of the group"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The business group cannot be found")
+ })
public Response addTutor(@PathParam("groupKey") Long groupKey, @PathParam("identityKey") Long identityKey, @Context HttpServletRequest request) {
try {
if(!isGroupManager(request)) {
@@ -785,6 +857,12 @@ public class LearningGroupWebService {
*/
@DELETE
@Path("{groupKey}/owners/{identityKey}")
+ @Operation(summary = "Removes the owner from the group", description = "Removes the owner from the group")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The user is removed as owner from the group"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The business group or the user cannot be found")
+ })
public Response removeTutor(@PathParam("groupKey") Long groupKey, @PathParam("identityKey") Long identityKey, @Context HttpServletRequest request) {
try {
if(!isGroupManager(request)) {
@@ -819,6 +897,12 @@ public class LearningGroupWebService {
*/
@PUT
@Path("{groupKey}/participants/{identityKey}")
+ @Operation(summary = "Adds a participant to the group", description = "Adds a participant to the group")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The user is added as participant of the group"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The business group or the user cannot be found")
+ })
public Response addParticipant(@PathParam("groupKey") Long groupKey, @PathParam("identityKey") Long identityKey, @Context HttpServletRequest request) {
try {
if(!isGroupManager(request)) {
@@ -858,6 +942,12 @@ public class LearningGroupWebService {
*/
@DELETE
@Path("{groupKey}/participants/{identityKey}")
+ @Operation(summary = "Removes a participant from the group", description = "Removes a participant from the group")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The user is remove from the group as participant"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The business group or the user cannot be found")
+ })
public Response removeParticipant(@PathParam("groupKey") Long groupKey, @PathParam("identityKey") Long identityKey, @Context HttpServletRequest request) {
try {
if(!isGroupManager(request)) {
diff --git a/src/main/java/org/olat/restapi/group/MyGroupWebService.java b/src/main/java/org/olat/restapi/group/MyGroupWebService.java
index a283b4a0218..806fbf221e8 100644
--- a/src/main/java/org/olat/restapi/group/MyGroupWebService.java
+++ b/src/main/java/org/olat/restapi/group/MyGroupWebService.java
@@ -52,6 +52,13 @@ import org.olat.restapi.support.vo.GroupVO;
import org.olat.restapi.support.vo.GroupVOes;
import org.springframework.beans.factory.annotation.Autowired;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+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;
+
/**
*
* Description:<br>
@@ -90,6 +97,12 @@ public class MyGroupWebService {
* @return The list of groups informations
*/
@GET
+ @Operation(summary = "Return all groups of a user where the user is coach or participant", description = "Return all groups of a user where the user is coach or participant")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The groups of the user", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = GroupVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = GroupVO.class))) }),
+ @ApiResponse(responseCode = "404", description = "The identity not found") })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getUserGroupList(@QueryParam("start") @DefaultValue("0") Integer start, @QueryParam("limit") @DefaultValue("25") Integer limit,
@QueryParam("externalId") String externalId, @QueryParam("managed") Boolean managed,
@@ -115,6 +128,12 @@ public class MyGroupWebService {
*/
@GET
@Path("owner")
+ @Operation(summary = "Return all groups of a user where the user is coach/owner", description = "Return all groups of a user where the user is coach/owner")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The groups of the user", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = GroupVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = GroupVO.class))) }),
+ @ApiResponse(responseCode = "404", description = "The identity not found") })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getOwnedGroupList(@QueryParam("start") @DefaultValue("0") Integer start, @QueryParam("limit") @DefaultValue("25") Integer limit,
@QueryParam("externalId") String externalId, @QueryParam("managed") Boolean managed,
@@ -139,6 +158,12 @@ public class MyGroupWebService {
*/
@GET
@Path("participant")
+ @Operation(summary = "Return all groups of a user where the user is participant", description = "Return all groups of a user where the user is participant")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The groups of the user", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = GroupVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = GroupVO.class))) }),
+ @ApiResponse(responseCode = "404", description = "The identity not found") })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getParticipatingGroupList(@QueryParam("start") @DefaultValue("0") Integer start, @QueryParam("limit") @DefaultValue("25") Integer limit,
@QueryParam("externalId") String externalId, @QueryParam("managed") Boolean managed,
@@ -203,6 +228,12 @@ public class MyGroupWebService {
*/
@GET
@Path("infos")
+ @Operation(summary = "Return all groups with information of a user", description = "Return all groups with information of a user. Paging is mandatory")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The groups of the user", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = GroupInfoVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = GroupInfoVO.class))) }),
+ @ApiResponse(responseCode = "406", description = "The request hasn't paging information") })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getUserGroupInfosList(@QueryParam("start") @DefaultValue("0") Integer start,
@QueryParam("limit") @DefaultValue("25") Integer limit,
diff --git a/src/main/java/org/olat/restapi/repository/CatalogWebService.java b/src/main/java/org/olat/restapi/repository/CatalogWebService.java
index 38ed5c9f707..af448e7bb09 100644
--- a/src/main/java/org/olat/restapi/repository/CatalogWebService.java
+++ b/src/main/java/org/olat/restapi/repository/CatalogWebService.java
@@ -77,6 +77,12 @@ import org.olat.user.restapi.UserVOFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+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.tags.Tag;
/**
@@ -115,6 +121,9 @@ public class CatalogWebService {
*/
@GET
@Path("version")
+ @Operation(summary = "Retrieves the version of the Catalog Web Service", description = "Retrieves the version of the Catalog Web Service")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The version of this specific Web Service") })
@Produces(MediaType.TEXT_PLAIN)
public Response getVersion() {
return Response.ok(VERSION).build();
@@ -129,6 +138,12 @@ public class CatalogWebService {
* @return The response
*/
@GET
+ @Operation(summary = "Returns the list of root catalog entries", description = "Returns the list of root catalog entries")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "Array of results for the whole the course", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = CatalogEntryVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = CatalogEntryVO.class))) })
+ })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getRoots(@Context HttpServletRequest httpRequest, @Context Request request) {
List<CatalogEntry> rootEntries = catalogManager.getRootCatalogEntries();
@@ -158,6 +173,12 @@ public class CatalogWebService {
*/
@GET
@Path("{path:.*}")
+ @Operation(summary = "Returns the metadata of the catalog entry", description = "Returns the metadata of the catalog entry")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The catalog entry", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = CatalogEntryVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = CatalogEntryVO.class)) })
+ })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getCatalogEntry(@PathParam("path") List<PathSegment> path, @Context UriInfo uriInfo,
@Context HttpServletRequest httpRequest, @Context Request request) {
@@ -195,6 +216,13 @@ public class CatalogWebService {
*/
@GET
@Path("{path:.*}/children")
+ @Operation(summary = "Returns a list of catalog entries", description = "Returns a list of catalog entries")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The list of catalog entries", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = CatalogEntryVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = CatalogEntryVO.class))) }),
+ @ApiResponse(responseCode = "404", description = "The path could not be resolved to a valid catalog entry")
+ })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getChildren(@PathParam("path") List<PathSegment> path, @QueryParam("start") @DefaultValue("0") Integer start,
@QueryParam("limit") @DefaultValue("25") Integer limit, @Context HttpServletRequest httpRequest, @Context Request request) {
@@ -255,6 +283,14 @@ public class CatalogWebService {
*/
@PUT
@Path("{path:.*}")
+ @Operation(summary = "Add a catalog", description = "Adds a catalog entry under the path specified in the URL")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The catalog entry", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = CatalogEntryVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = CatalogEntryVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "Not authorized"),
+ @ApiResponse(responseCode = "404", description = "The path could not be resolved to a valid catalog entry")
+ })
@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response addCatalogEntry(@PathParam("path") List<PathSegment> path,
@@ -293,6 +329,14 @@ public class CatalogWebService {
*/
@PUT
@Path("{path:.*}")
+ @Operation(summary = "Add a catalog", description = "Adds a catalog entry under the path specified in the URL")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The catalog entry", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = CatalogEntryVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = CatalogEntryVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "Not authorized"),
+ @ApiResponse(responseCode = "404", description = "The path could not be resolved to a valid catalog entry")
+ })
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response addCatalogEntry(@PathParam("path") List<PathSegment> path, CatalogEntryVO entryVo,
@@ -368,6 +412,14 @@ public class CatalogWebService {
*/
@POST
@Path("{path:.*}")
+ @Operation(summary = "Update a catalog", description = "Updates the catalog entry under the path specified in the URL")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The catalog entry", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = CatalogEntryVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = CatalogEntryVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "Not authorized"),
+ @ApiResponse(responseCode = "404", description = "The path could not be resolved to a valid catalog entry")
+ })
@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response updatePostCatalogEntry(@PathParam("path") List<PathSegment> path,
@@ -400,6 +452,14 @@ public class CatalogWebService {
*/
@POST
@Path("{path:.*}")
+ @Operation(summary = "Update a catalog", description = "Updates the catalog entry with the path specified in the URL")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The catalog entry", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = CatalogEntryVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = CatalogEntryVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "Not authorized"),
+ @ApiResponse(responseCode = "404", description = "The path could not be resolved to a valid catalog entry")
+ })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response updateCatalogEntry(@PathParam("path") List<PathSegment> path,
@QueryParam("name") String name, @QueryParam("description") String description,
@@ -429,6 +489,14 @@ public class CatalogWebService {
*/
@POST
@Path("{path:.*}")
+ @Operation(summary = "Update a catalog", description = "Updates the catalog entry with the path specified in the URL")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The catalog entry", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = CatalogEntryVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = CatalogEntryVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "Not authorized"),
+ @ApiResponse(responseCode = "404", description = "The path could not be resolved to a valid catalog entry")
+ })
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response updateCatalogEntry(@PathParam("path") List<PathSegment> path,
@@ -508,6 +576,12 @@ public class CatalogWebService {
*/
@DELETE
@Path("{path:.*}")
+ @Operation(summary = "Delete a catalog", description = "Deletes the catalog entry with the path specified in the URL")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The catalog entry"),
+ @ApiResponse(responseCode = "401", description = "Not authorized"),
+ @ApiResponse(responseCode = "404", description = "The path could not be resolved to a valid catalog entry")
+ })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response deleteCatalogEntry(@PathParam("path") List<PathSegment> path, @Context HttpServletRequest httpRequest) {
Long key = getCatalogEntryKeyFromPath(path);
@@ -554,6 +628,14 @@ public class CatalogWebService {
*/
@GET
@Path("{path:.*}/owners")
+ @Operation(summary = "Get the owners of the local sub tree", description = "Get the owners of the local sub tree")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The catalog entry", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = CatalogEntryVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = CatalogEntryVO.class))) }),
+ @ApiResponse(responseCode = "401", description = "Not authorized"),
+ @ApiResponse(responseCode = "404", description = "The path could not be resolved to a valid catalog entry")
+ })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getOwners(@PathParam("path") List<PathSegment> path, @Context HttpServletRequest httpRequest) {
Long key = getCatalogEntryKeyFromPath(path);
@@ -594,6 +676,14 @@ public class CatalogWebService {
*/
@GET
@Path("{path:.*}/owners/{identityKey}")
+ @Operation(summary = "Retrieves data of an owner of the local sub tree", description = "Retrieves data of an owner of the local sub tree")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The catalog entry", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = CatalogEntryVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = CatalogEntryVO.class))) }),
+ @ApiResponse(responseCode = "401", description = "Not authorized"),
+ @ApiResponse(responseCode = "404", description = "The path could not be resolved to a valid catalog entry")
+ })
public Response getOwner(@PathParam("path") List<PathSegment> path, @PathParam("identityKey") Long identityKey,
@Context HttpServletRequest httpRequest) {
Long key = getCatalogEntryKeyFromPath(path);
@@ -639,6 +729,14 @@ public class CatalogWebService {
*/
@PUT
@Path("{path:.*}/owners/{identityKey}")
+ @Operation(summary = "Add an owner of the local sub tree", description = "Add an owner of the local sub tree")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The catalog entry", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = CatalogEntryVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = CatalogEntryVO.class))) }),
+ @ApiResponse(responseCode = "401", description = "Not authorized"),
+ @ApiResponse(responseCode = "404", description = "The path could not be resolved to a valid catalog entry")
+ })
public Response addOwner(@PathParam("path") List<PathSegment> path, @PathParam("identityKey") Long identityKey,
@Context HttpServletRequest httpRequest) {
Long key = getCatalogEntryKeyFromPath(path);
@@ -690,6 +788,12 @@ public class CatalogWebService {
*/
@DELETE
@Path("{path:.*}/owners/{identityKey}")
+ @Operation(summary = "Remove an owner of the local sub tree", description = "Remove an owner of the local sub tree")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The catalog entry"),
+ @ApiResponse(responseCode = "401", description = "Not authorized"),
+ @ApiResponse(responseCode = "404", description = "The path could not be resolved to a valid catalog entry")
+ })
public Response removeOwner(@PathParam("path") List<PathSegment> path, @PathParam("identityKey") Long identityKey,
@Context HttpServletRequest httpRequest) {
Long key = getCatalogEntryKeyFromPath(path);
diff --git a/src/main/java/org/olat/restapi/repository/RepositoryEntriesWebService.java b/src/main/java/org/olat/restapi/repository/RepositoryEntriesWebService.java
index 1869b1c50ef..15ee9a429d7 100644
--- a/src/main/java/org/olat/restapi/repository/RepositoryEntriesWebService.java
+++ b/src/main/java/org/olat/restapi/repository/RepositoryEntriesWebService.java
@@ -86,6 +86,7 @@ import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.info.License;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.servers.Server;
@@ -139,6 +140,10 @@ public class RepositoryEntriesWebService {
*/
@GET
@Path("version")
+ @Operation(summary = "The version number of this web service", description = "The version number of this web service")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The version number of this web service" )})
+
@Produces(MediaType.TEXT_PLAIN)
public Response getVersion() {
return Response.ok(VERSION).build();
@@ -166,8 +171,8 @@ public class RepositoryEntriesWebService {
@ApiResponse(responseCode = "200",
description = "JVM system properties of a particular host.",
content = {
- @Content(mediaType = "application/json", schema = @Schema(implementation = RepositoryEntryVO[].class)),
- @Content(mediaType = "application/xml", schema = @Schema(implementation = RepositoryEntryVO[].class))
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = RepositoryEntryVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = RepositoryEntryVO.class)))
}
)}
)
@@ -239,6 +244,12 @@ public class RepositoryEntriesWebService {
*/
@GET
@Path("search")
+ @Operation(summary = "Search for repository entries", description = "Search for repository entries, possible search attributes are name, author and type")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "Search for repository entries", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = RepositoryEntryVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = RepositoryEntryVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient") })
@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
public Response searchEntries(@QueryParam("type") String type, @QueryParam("author") @DefaultValue("*") String author,
@QueryParam("name") @DefaultValue("*") String name, @QueryParam("myentries") @DefaultValue("false") boolean myEntries,
@@ -306,6 +317,12 @@ public class RepositoryEntriesWebService {
* @return
*/
@PUT
+ @Operation(summary = "Import a resource in the repository", description = "Import a resource in the repository")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "Import the resource and return the repository entry", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = RepositoryEntryVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = RepositoryEntryVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient") })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
@Consumes({MediaType.MULTIPART_FORM_DATA})
public Response putResource(@Context HttpServletRequest request) {
diff --git a/src/main/java/org/olat/restapi/repository/RepositoryEntryLifecycleWebService.java b/src/main/java/org/olat/restapi/repository/RepositoryEntryLifecycleWebService.java
index 9b494995adc..f4641d58036 100644
--- a/src/main/java/org/olat/restapi/repository/RepositoryEntryLifecycleWebService.java
+++ b/src/main/java/org/olat/restapi/repository/RepositoryEntryLifecycleWebService.java
@@ -37,9 +37,16 @@ import org.olat.core.id.Roles;
import org.olat.repository.manager.RepositoryEntryLifecycleDAO;
import org.olat.repository.model.RepositoryEntryLifecycle;
import org.olat.restapi.support.vo.RepositoryEntryLifecycleVO;
+import org.olat.restapi.support.vo.RepositoryEntryVO;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+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.tags.Tag;
/**
@@ -67,6 +74,11 @@ public class RepositoryEntryLifecycleWebService {
* @return
*/
@GET
+ @Operation(summary = "List all public lifecycles", description = "List all public lifecycles")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "List all entries in the repository", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = RepositoryEntryVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = RepositoryEntryVO.class))) })})
@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
public Response getPublicLifeCycles(@Context HttpServletRequest httpRequest) {
Roles roles = getRoles(httpRequest);
diff --git a/src/main/java/org/olat/restapi/repository/RepositoryEntryWebService.java b/src/main/java/org/olat/restapi/repository/RepositoryEntryWebService.java
index e9b0c60bb7e..174afb118b5 100644
--- a/src/main/java/org/olat/restapi/repository/RepositoryEntryWebService.java
+++ b/src/main/java/org/olat/restapi/repository/RepositoryEntryWebService.java
@@ -111,6 +111,13 @@ import org.olat.user.restapi.UserVOFactory;
import org.olat.util.logging.activity.LoggingResourceable;
import org.springframework.beans.factory.annotation.Autowired;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+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;
+
/**
* Description:<br>
* Repository entry resource
@@ -167,6 +174,12 @@ public class RepositoryEntryWebService {
* @return
*/
@GET
+ @Operation(summary = "get a resource in the repository", description = "get a resource in the repository")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "Get the repository resource", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = RepositoryEntryVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = RepositoryEntryVO.class)) }),
+ @ApiResponse(responseCode = "404", description = "The repository entry not found") })
@Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
public Response getById(@Context Request request) {
Date lastModified = entry.getLastModified();
@@ -196,6 +209,9 @@ public class RepositoryEntryWebService {
* @return The web service for lecture blocks.
*/
@Path("lectureblocks")
+ @Operation(summary = "Get the web service for the lecture blocks", description = "To get the web service for the lecture blocks of a specific learning resource")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "A web service to manage the lecture blocks") })
public LectureBlocksWebService getLectureBlocksWebService(@Context HttpServletRequest request)
throws WebApplicationException {
boolean administrator = isLectureManager(request);
@@ -210,6 +226,9 @@ public class RepositoryEntryWebService {
* @return The web service for reminders.
*/
@Path("reminders")
+ @Operation(summary = "To get the web service for the reminders of a specific course", description = "To get the web service for the reminders of a specific course")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The web service for reminders") })
public RemindersWebService getRemindersWebService(@Context HttpServletRequest request) {
boolean administrator = isAuthorEditor(request);
RemindersWebService service = new RemindersWebService(entry, administrator);
@@ -219,6 +238,11 @@ public class RepositoryEntryWebService {
@GET
@Path("curriculum/elements")
+ @Operation(summary = "Get elements", description = "Get elements")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The elements", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = CurriculumElementVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = CurriculumElementVO.class))) }) })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getCurriculumElements() {
List<CurriculumElement> curriculumElements = curriculumService.getCurriculumElements(entry);
@@ -242,6 +266,12 @@ public class RepositoryEntryWebService {
*/
@GET
@Path("owners")
+ @Operation(summary = "Returns the list of owners", description = "Returns the list of owners of the repository entry specified by the groupKey")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "Owners of the repository entry", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = UserVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = UserVO.class))) }),
+ @ApiResponse(responseCode = "404", description = "The course not found") })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getOwners(@Context HttpServletRequest request) {
if(!isAuthorEditor(request)) {
@@ -262,6 +292,11 @@ public class RepositoryEntryWebService {
*/
@PUT
@Path("owners/{identityKey}")
+ @Operation(summary = "Adds an owner to the repository entry", description = "Adds an owner to the repository entry")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The user is added as owner of the repository entry"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The repository entry or the user cannot be found") })
public Response addOwner(@PathParam("identityKey") Long identityKey, @Context HttpServletRequest request) {
if(!isAuthorEditor(request)) {
return Response.serverError().status(Status.UNAUTHORIZED).build();
@@ -280,6 +315,11 @@ public class RepositoryEntryWebService {
@PUT
@Path("owners")
+ @Operation(summary = "Add owners to the repository entry", description = "Add owners to the repository entry")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The owners are added to the repository entry"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The repository entry or the user cannot be found") })
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response addOwners(UserVO[] owners, @Context HttpServletRequest request) {
if(!isAuthorEditor(request)) {
@@ -305,6 +345,11 @@ public class RepositoryEntryWebService {
*/
@DELETE
@Path("owners/{identityKey}")
+ @Operation(summary = "Removes the owner from the repository entry", description = "Removes the owner from the repository entry")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The user is removed as owner from the repository entry"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The repository entry or the user cannot be found") })
public Response removeOwner(@PathParam("identityKey") Long identityKey, @Context HttpServletRequest request) {
try {
if (!isAuthorEditor(request)) {
@@ -338,6 +383,12 @@ public class RepositoryEntryWebService {
*/
@GET
@Path("coaches")
+ @Operation(summary = "Returns the list of coaches of the repository entry", description = "Returns the list of coaches of the repository entry")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "Coaches of the repository entry", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = UserVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = UserVO.class))) }),
+ @ApiResponse(responseCode = "404", description = "The repository entry cannot be found") })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getCoaches(@Context HttpServletRequest request) {
if(!isAuthorEditor(request)) {
@@ -358,6 +409,10 @@ public class RepositoryEntryWebService {
*/
@PUT
@Path("coaches/{identityKey}")
+ @Operation(summary = "Adds a coach to the repository entry", description = "Adds a coach to the repository entry")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The user is added as coach of the repository entry"),
+ @ApiResponse(responseCode = "404", description = "The repository entry cannot be found") })
public Response addCoach(@PathParam("identityKey") Long identityKey,
@Context HttpServletRequest request) {
if(!isAuthorEditor(request)) {
@@ -377,6 +432,10 @@ public class RepositoryEntryWebService {
@PUT
@Path("coaches")
+ @Operation(summary = "Adds coaches to the repository entry", description = "Adds coaches to the repository entry")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The coaches are added to the repository entry"),
+ @ApiResponse(responseCode = "404", description = "The repository entry cannot be found") })
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response addCoach(UserVO[] coaches, @Context HttpServletRequest request) {
if(!isAuthorEditor(request)) {
@@ -402,6 +461,11 @@ public class RepositoryEntryWebService {
*/
@DELETE
@Path("coaches/{identityKey}")
+ @Operation(summary = "Removes the coach from the repository entry", description = "Removes the coach from the repository entry")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The user is removed as owner from the repository entry"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The repository entry or the user cannot be found") })
public Response removeCoach(@PathParam("identityKey") Long identityKey, @Context HttpServletRequest request) {
if (!isAuthorEditor(request)) {
return Response.serverError().status(Status.UNAUTHORIZED).build();
@@ -430,6 +494,12 @@ public class RepositoryEntryWebService {
*/
@GET
@Path("participants")
+ @Operation(summary = "Returns the list of participants of the repository entry", description = "Returns the list of participants of the repository entry")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "Participants of the repository entry", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = UserVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = UserVO.class))) }),
+ @ApiResponse(responseCode = "404", description = "The repository entry cannot be found") })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getParticipants( @Context HttpServletRequest request) {
if(!isAuthorEditor(request)) {
@@ -450,6 +520,11 @@ public class RepositoryEntryWebService {
*/
@PUT
@Path("participants/{identityKey}")
+ @Operation(summary = "Adds a participant to the repository entry", description = "Adds a participant to the repository entry")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The user is added as participant of the repository entry"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The repository entry or the user cannot be found") })
public Response addParticipant(@PathParam("identityKey") Long identityKey, @Context HttpServletRequest request) {
if(!isAuthorEditor(request)) {
return Response.serverError().status(Status.UNAUTHORIZED).build();
@@ -468,6 +543,11 @@ public class RepositoryEntryWebService {
@PUT
@Path("participants")
+ @Operation(summary = "Adds participants to the repository entry", description = "Adds participants to the repository entry")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The participants are added to the repository entry"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The repository entry or the user cannot be found") })
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response addParticipants(UserVO[] participants, @Context HttpServletRequest request) {
if(!isAuthorEditor(request)) {
@@ -501,6 +581,11 @@ public class RepositoryEntryWebService {
*/
@DELETE
@Path("participants/{identityKey}")
+ @Operation(summary = "Removes the participant from the repository entry", description = "Removes the participant from the repository entry")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The user is removed as participant from the repository entry"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The repository entry or the user cannot be found") })
public Response removeParticipant(@PathParam("identityKey") Long identityKey, @Context HttpServletRequest request) {
if (!isAuthorEditor(request)) {
return Response.serverError().status(Status.UNAUTHORIZED).build();
@@ -533,6 +618,13 @@ public class RepositoryEntryWebService {
*/
@GET
@Path("file")
+ @Operation(summary = "Download the export zip file of a repository entry", description = "Download the export zip file of a repository entry")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "Download the repository entry as export zip file"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The repository entry cannot be found"),
+ @ApiResponse(responseCode = "406", description = "Download of this resource is not possible"),
+ @ApiResponse(responseCode = "409", description = "The resource is locked")})
@Produces({ "application/zip", MediaType.APPLICATION_OCTET_STREAM })
public Response getRepoFileById(@Context HttpServletRequest request, @Context HttpServletResponse response) {
RepositoryHandler typeToDownload = repositoryHandlerFactory.getRepositoryHandler(entry);
@@ -648,6 +740,11 @@ public class RepositoryEntryWebService {
* @return
*/
@POST
+ @Operation(summary = "Replace a resource in the repository", description = "Replace a resource in the repository and update its display name. The implementation is\n" +
+ " limited to CP")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "Replace the resource and return the updated repository entry"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient")})
@Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
@Consumes({ MediaType.MULTIPART_FORM_DATA })
public Response replaceResource(@Context HttpServletRequest request) {
@@ -738,6 +835,11 @@ public class RepositoryEntryWebService {
* object representing the course.
*/
@DELETE
+ @Operation(summary = "Delete a resource by id", description = "Delete a resource by id")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The metadatas of the deleted resource"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The course not found")})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response deleteCourse(@Context HttpServletRequest request) {
if(!isAuthor(request)) {
@@ -775,6 +877,18 @@ public class RepositoryEntryWebService {
* object representing the course.
*/
@POST
+ @Operation(summary = "Change the status of a course by id", description = "Change the status of a course by id. The possible status are:\n" +
+ " * <ul>\n" +
+ " * <li>closed</li>\n" +
+ " * <li>unclosed</li>\n" +
+ " * <li>unpublished</li>\n" +
+ " * <li>deleted</li>\n" +
+ " * <li>restored</li>\n" +
+ " * </ul>")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The metadatas of the deleted resource"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The course not found")})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
@Path("status")
public Response postStatus(@FormParam("newStatus") String newStatus, @Context HttpServletRequest request) {
@@ -820,6 +934,13 @@ public class RepositoryEntryWebService {
*/
@GET
@Path("access")
+ @Operation(summary = "Get the access configuration of the repository entry", description = "Get the access configuration of the repository entry")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The access configuration of the repository entry", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = RepositoryEntryAccessVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = RepositoryEntryAccessVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The course not found")})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getAccess(@Context HttpServletRequest request) {
if(!isAuthor(request) && !isAuthorEditor(request)) {
@@ -845,6 +966,15 @@ public class RepositoryEntryWebService {
*/
@POST
@Path("access")
+ @Operation(summary = "Update the access configuration of the repository entry", description = "Update the access configuration of the repository entry. Attention! It's\n" +
+ " a low level method which only change the status without the stuff\n" +
+ " done by the change status methods. Use it only if you know what you do")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The access configuration of the repository entry", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = RepositoryEntryAccessVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = RepositoryEntryAccessVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The course not found")})
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response updateAccess(RepositoryEntryAccessVO accessVo, @Context HttpServletRequest request) {
@@ -864,6 +994,13 @@ public class RepositoryEntryWebService {
@GET
@Path("organisations")
+ @Operation(summary = "Get organisations", description = "Get organisations")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The list of organisations", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = OrganisationVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = OrganisationVO.class))) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "Not found")})
public Response getOrganisations(@Context HttpServletRequest httpRequest) {
if (!isAuthorEditor(httpRequest)) {
return Response.serverError().status(Status.UNAUTHORIZED).build();
@@ -879,6 +1016,11 @@ public class RepositoryEntryWebService {
@PUT
@Path("organisations/{organisationKey}")
+ @Operation(summary = "Put organisation", description = "Put organisation")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "Organisation was put"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "Not found")})
public Response addOrganisation(@PathParam("organisationKey") Long organisationKey, @Context HttpServletRequest httpRequest) {
Organisation organisationToAdd = organisationService.getOrganisation(new OrganisationRefImpl(organisationKey));
if (!isAuthorEditor(httpRequest) && !isManager(organisationToAdd, httpRequest)) {
@@ -900,6 +1042,11 @@ public class RepositoryEntryWebService {
@DELETE
@Path("organisations/{organisationKey}")
+ @Operation(summary = "Remove organisation", description = "Remove organisation")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "Organisation was deleted"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "Not found")})
public Response removeOrganisation(@PathParam("organisationKey") Long organisationKey, @Context HttpServletRequest httpRequest) {
Organisation organisationToRemove = organisationService.getOrganisation(new OrganisationRefImpl(organisationKey));
if (!isAuthorEditor(httpRequest) && !isManager(organisationToRemove, httpRequest)) {
@@ -913,6 +1060,13 @@ public class RepositoryEntryWebService {
@GET
@Path("taxonomy/levels")
+ @Operation(summary = "Get levels", description = "Get levels")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The list of levels", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = TaxonomyLevelVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = TaxonomyLevelVO.class))) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "Not found")})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getTaxonomyLevels(@Context HttpServletRequest request) {
if(!isAuthorEditor(request)) {
@@ -929,6 +1083,11 @@ public class RepositoryEntryWebService {
@PUT
@Path("taxonomy/levels/{taxonomyLevelKey}")
+ @Operation(summary = "Get level", description = "Get level")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The level put"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "Not found")})
public Response putTaxonomyLevel(@PathParam("taxonomyLevelKey") Long taxonomyLevelKey) {
List<TaxonomyLevel> levels = repositoryEntryToTaxonomyLevelDao.getTaxonomyLevels(entry);
for(TaxonomyLevel level:levels) {
@@ -946,6 +1105,11 @@ public class RepositoryEntryWebService {
@DELETE
@Path("taxonomy/levels/{taxonomyLevelKey}")
+ @Operation(summary = "Remove level", description = "Remove level")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The level was removed"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "Not found")})
public Response deleteTaxonomyLevel(@PathParam("taxonomyLevelKey") Long taxonomyLevelKey) {
TaxonomyLevel level = taxonomyService.getTaxonomyLevel(new TaxonomyLevelRefImpl(taxonomyLevelKey));
if(level == null) {
diff --git a/src/main/java/org/olat/restapi/repository/course/CourseGroupWebService.java b/src/main/java/org/olat/restapi/repository/course/CourseGroupWebService.java
index 65f7ff5ac9e..cd224ceb828 100644
--- a/src/main/java/org/olat/restapi/repository/course/CourseGroupWebService.java
+++ b/src/main/java/org/olat/restapi/repository/course/CourseGroupWebService.java
@@ -156,6 +156,7 @@ public class CourseGroupWebService {
* @return
*/
@Path("{groupKey}/forum")
+ @Operation(summary = "Return the Forum web service", description = "Return the Forum web service")
public ForumWebService getForum(@PathParam("groupKey") Long groupKey, @Context HttpServletRequest request) {
BusinessGroupService bgs = CoreSpringFactory.getImpl(BusinessGroupService.class);
BusinessGroup bg = bgs.loadBusinessGroup(groupKey);
diff --git a/src/main/java/org/olat/restapi/repository/course/CourseWebService.java b/src/main/java/org/olat/restapi/repository/course/CourseWebService.java
index a0590a225ef..bbc3c7863a1 100644
--- a/src/main/java/org/olat/restapi/repository/course/CourseWebService.java
+++ b/src/main/java/org/olat/restapi/repository/course/CourseWebService.java
@@ -109,6 +109,13 @@ import org.springframework.beans.factory.annotation.Autowired;
import com.thoughtworks.xstream.XStream;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+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;
+
/**
* Description:<br>
* This web service will handle the functionality related to <code>Course</code>
@@ -710,6 +717,13 @@ public class CourseWebService {
*/
@GET
@Path("authors")
+ @Operation(summary = "Get all owners and authors of the course", description = "Get all owners and authors of the course")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The array of authors", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = UserVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = UserVO.class))) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The course not found") })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getAuthors(@Context HttpServletRequest httpRequest) {
if (!isManager(httpRequest)) {
@@ -739,6 +753,13 @@ public class CourseWebService {
*/
@GET
@Path("tutors")
+ @Operation(summary = "Get all coaches of the course", description = "Get all coaches of the course (don't follow the groups)")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The array of coaches", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = UserVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = UserVO.class))) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The course not found") })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getTutors(@Context HttpServletRequest httpRequest) {
if (!isManager(httpRequest)) {
@@ -768,6 +789,13 @@ public class CourseWebService {
*/
@GET
@Path("participants")
+ @Operation(summary = "Get all participants of the course", description = "Get all participants of the course (don't follow the groups)")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The array of participants", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = UserVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = UserVO.class))) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The course not found") })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getParticipants(@Context HttpServletRequest httpRequest) {
if (!isManager(httpRequest)) {
@@ -798,6 +826,13 @@ public class CourseWebService {
*/
@GET
@Path("authors/{identityKey}")
+ @Operation(summary = "Get this specific author and owner of the course", description = "Get this specific author and owner of the course")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The author", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = UserVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = UserVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The course not found or the user is not an onwer or author of the course") })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getAuthor(@PathParam("identityKey") Long identityKey,
@Context HttpServletRequest httpRequest) {
@@ -826,6 +861,11 @@ public class CourseWebService {
*/
@PUT
@Path("authors/{identityKey}")
+ @Operation(summary = "Add an owner and author to the course", description = "Add an owner and author to the course")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The user is an author and owner of the course"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The course or the user not found") })
public Response addAuthor(@PathParam("identityKey") Long identityKey,
@Context HttpServletRequest httpRequest) {
if (!isManager(httpRequest)) {
@@ -856,6 +896,11 @@ public class CourseWebService {
@PUT
@Path("authors")
+ @Operation(summary = "Add authors to the course", description = "Add authors to the course")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The authors have been added"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The course or the user not found") })
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response addAuthors(UserVO[] authors, @Context HttpServletRequest httpRequest) {
if (!isManager(httpRequest)) {
@@ -892,6 +937,11 @@ public class CourseWebService {
*/
@DELETE
@Path("authors/{identityKey}")
+ @Operation(summary = "Remove an owner and author to the course", description = "Remove an owner and author to the course")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The user was successfully removed as owner of the course"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The course or the user not found") })
public Response removeAuthor(@PathParam("identityKey") Long identityKey,
@Context HttpServletRequest httpRequest) {
if (!isManager(httpRequest)) {
@@ -923,6 +973,11 @@ public class CourseWebService {
*/
@PUT
@Path("tutors/{identityKey}")
+ @Operation(summary = "Add a coach to the course", description = "Add a coach to the course")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The user is a coach of the course"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The course or the user not found") })
public Response addCoach(@PathParam("identityKey") Long identityKey,
@Context HttpServletRequest httpRequest) {
if (!isManager(httpRequest)) {
@@ -947,6 +1002,11 @@ public class CourseWebService {
@PUT
@Path("tutors")
+ @Operation(summary = "Add tutors to the course", description = "Add tutors to the course")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The tutors have been added"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The course or the user not found") })
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response addCoaches(UserVO[] coaches, @Context HttpServletRequest httpRequest) {
if (!isManager(httpRequest)) {
@@ -975,6 +1035,11 @@ public class CourseWebService {
*/
@DELETE
@Path("tutors/{identityKey}")
+ @Operation(summary = "Remove a coach from the course", description = "Remove a coach from the course")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The user was successfully removed as coach of the course"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The course or the user not found") })
public Response removeCoach(@PathParam("identityKey") Long identityKey,
@Context HttpServletRequest httpRequest) {
if (!isManager(httpRequest)) {
@@ -1006,6 +1071,11 @@ public class CourseWebService {
*/
@PUT
@Path("participants/{identityKey}")
+ @Operation(summary = "Add an participant to the course", description = "Add an participant to the course")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The user is a participant of the course"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The course or the user not found") })
public Response addParticipant(@PathParam("identityKey") Long identityKey,
@Context HttpServletRequest httpRequest) {
if (!isManager(httpRequest)) {
@@ -1039,6 +1109,11 @@ public class CourseWebService {
*/
@PUT
@Path("participants")
+ @Operation(summary = "Add an participant to the course", description = "Add an participant to the course")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The user is a participant of the course"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The course or the user not found") })
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response addParticipants(UserVO[] participants,
@Context HttpServletRequest httpRequest) {
@@ -1068,6 +1143,11 @@ public class CourseWebService {
*/
@DELETE
@Path("participants/{identityKey}")
+ @Operation(summary = "Remove a participant from the course", description = "Remove a participant from the course")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The user was successfully removed as participant of the course"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The course or the user not found") })
public Response removeParticipant(@PathParam("identityKey") Long identityKey,
@Context HttpServletRequest httpRequest) {
if (!isManager(httpRequest)) {
diff --git a/src/main/java/org/olat/restapi/system/DatabaseWebService.java b/src/main/java/org/olat/restapi/system/DatabaseWebService.java
index d0fd0cc85fc..e99973c028e 100644
--- a/src/main/java/org/olat/restapi/system/DatabaseWebService.java
+++ b/src/main/java/org/olat/restapi/system/DatabaseWebService.java
@@ -32,6 +32,13 @@ import org.olat.core.commons.persistence.DBFactory;
import org.olat.restapi.system.vo.DatabaseVO;
import org.olat.restapi.system.vo.HibernateStatisticsVO;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+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;
+
/**
*
* @author srosse, stephane.rosse@frentix.com, http://www.frentix.com
@@ -50,6 +57,12 @@ public class DatabaseWebService {
* @return The informations about runtime, uptime, classes loaded, memory summary...
*/
@GET
+ @Operation(summary = "Return the statistics about database and hibernate", description = "Return the statistics about database and hibernate")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The version of the instance", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = DatabaseVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = DatabaseVO.class))) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient") })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getDatabaseStatistics() {
DatabaseConnectionVO connections = CoreSpringFactory.getImpl(DatabaseStatsManager.class)
diff --git a/src/main/java/org/olat/restapi/system/IndexerWebService.java b/src/main/java/org/olat/restapi/system/IndexerWebService.java
index d2be7f89c5f..1f745c243c3 100644
--- a/src/main/java/org/olat/restapi/system/IndexerWebService.java
+++ b/src/main/java/org/olat/restapi/system/IndexerWebService.java
@@ -34,6 +34,12 @@ import org.olat.search.service.SearchServiceFactory;
import org.olat.search.service.SearchServiceStatusImpl;
import org.olat.search.service.indexer.FullIndexerStatus;
+import io.swagger.v3.oas.annotations.Operation;
+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;
+
/**
*
* @author srosse, stephane.rosse@frentix.com, http://www.frentix.com
@@ -50,6 +56,12 @@ public class IndexerWebService {
* @return The statistics about the indexer
*/
@GET
+ @Operation(summary = "Return the statistics about the indexer", description = "Return the statistics about the indexer")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "Statistics about the indexer", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = IndexerStatisticsVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = IndexerStatisticsVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient") })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getStatistics() {
IndexerStatisticsVO stats = getIndexerStatistics();
@@ -65,6 +77,10 @@ public class IndexerWebService {
*/
@GET
@Path("status")
+ @Operation(summary = "Return the status of the indexer", description = "Return the status of the indexer: running, stopped")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "he status of the indexer"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient") })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getStatus() {
String status;
@@ -86,6 +102,10 @@ public class IndexerWebService {
*/
@GET
@Path("status")
+ @Operation(summary = "Return the status of the indexer", description = "Return the status of the indexer: running, stopped")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The status of the indexer"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient") })
@Produces({MediaType.TEXT_PLAIN})
public Response getPlainTextStatus() {
String status;
@@ -107,6 +127,11 @@ public class IndexerWebService {
*/
@POST
@Path("status")
+ @Operation(summary = "Update the status of the indexer", description = "Update the status of the indexer: running, stopped.\n" +
+ " Running start the indexer, stopped, stop it.")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The status has changed"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient") })
public Response setStatus(@FormParam("status") String status) {
if(FullIndexerStatus.STATUS_RUNNING.equals(status)) {
SearchServiceFactory.getService().startIndexing();
diff --git a/src/main/java/org/olat/restapi/system/MemoryWebService.java b/src/main/java/org/olat/restapi/system/MemoryWebService.java
index 88bd95eb91a..1a81e02d7ac 100644
--- a/src/main/java/org/olat/restapi/system/MemoryWebService.java
+++ b/src/main/java/org/olat/restapi/system/MemoryWebService.java
@@ -42,6 +42,12 @@ import org.olat.restapi.system.vo.MemoryPoolVO;
import org.olat.restapi.system.vo.MemorySampleVO;
import org.olat.restapi.system.vo.MemoryVO;
+import io.swagger.v3.oas.annotations.Operation;
+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;
+
/**
*
@@ -91,6 +97,10 @@ public class MemoryWebService implements Sampler {
* @return The informations about the memory
*/
@GET
+ @Operation(summary = "Return informations about memory", description = "Return informations about memory")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "Informations about memory"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient") })
@Produces(MediaType.TEXT_PLAIN)
public Response getMemory() {
MemoryVO vo = createMemoryVO();
@@ -108,6 +118,12 @@ public class MemoryWebService implements Sampler {
* @return The informations about the memory
*/
@GET
+ @Operation(summary = "Return some informations about memory", description = "Return some informations about memory")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "A short summary of the number of classes", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = MemoryVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = MemoryVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient") })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getMemoryXml() {
MemoryVO vo = createMemoryVO();
@@ -127,6 +143,10 @@ public class MemoryWebService implements Sampler {
@GET
@Path("pools")
+ @Operation(summary = "Get pools", description = "Get the pools")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The pools"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient")})
@Produces(MediaType.TEXT_PLAIN)
public Response getMemoryPools() {
MemoryPoolVO[] voes = createMemoryPools();
@@ -139,6 +159,10 @@ public class MemoryWebService implements Sampler {
@GET
@Path("pools")
+ @Operation(summary = "Get pools", description = "Get the pools")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The pools"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient")})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getMemoryPoolsXml() {
MemoryPoolVO[] voes = createMemoryPools();
@@ -147,6 +171,10 @@ public class MemoryWebService implements Sampler {
@GET
@Path("samples")
+ @Operation(summary = "Get samples", description = "Get the samples")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The samples"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient")})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getSamplesXml(@QueryParam("from") String from, @QueryParam("to") String to, @QueryParam("lastSamples") Integer maxResults) {
List<MemorySampleVO> samples = new ArrayList<>(memorySamples);
diff --git a/src/main/java/org/olat/restapi/system/MonitoringWebService.java b/src/main/java/org/olat/restapi/system/MonitoringWebService.java
index 0c9d0eb6e7e..94deb688ca6 100644
--- a/src/main/java/org/olat/restapi/system/MonitoringWebService.java
+++ b/src/main/java/org/olat/restapi/system/MonitoringWebService.java
@@ -36,6 +36,12 @@ import org.olat.instantMessaging.InstantMessagingModule;
import org.olat.restapi.system.vo.MonitoringDependencyVO;
import org.olat.restapi.system.vo.MonitoringInfosVO;
+import io.swagger.v3.oas.annotations.Operation;
+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;
+
/**
*
* @author srosse, stephane.rosse@frentix.com, http://www.frentix.com
@@ -95,6 +101,14 @@ public class MonitoringWebService {
*/
@GET
@Path("configuration")
+ @Operation(summary = "Return the configuration of the monitoring", description = "Return the configuration of the monitoring, which probes are available,\n" +
+ " which dependency...")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "he version of the instance", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = MonitoringInfosVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = MonitoringInfosVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The course not found") })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getImplementedProbes() {
MonitoringInfosVO vo = new MonitoringInfosVO();
diff --git a/src/main/java/org/olat/restapi/system/OpenOLATStatisticsWebService.java b/src/main/java/org/olat/restapi/system/OpenOLATStatisticsWebService.java
index 97f5ab48c75..0f34d83af64 100644
--- a/src/main/java/org/olat/restapi/system/OpenOLATStatisticsWebService.java
+++ b/src/main/java/org/olat/restapi/system/OpenOLATStatisticsWebService.java
@@ -42,12 +42,18 @@ import org.olat.course.CourseModule;
import org.olat.group.BusinessGroupService;
import org.olat.portfolio.manager.InvitationDAO;
import org.olat.repository.RepositoryManager;
+import org.olat.restapi.system.vo.IndexerStatisticsVO;
import org.olat.restapi.system.vo.OpenOLATStatisticsVO;
import org.olat.restapi.system.vo.RepositoryStatisticsVO;
import org.olat.restapi.system.vo.SessionsVO;
import org.olat.restapi.system.vo.TasksVO;
import org.olat.restapi.system.vo.UserStatisticsVO;
+import io.swagger.v3.oas.annotations.Operation;
+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.tags.Tag;
/**
@@ -69,6 +75,12 @@ public class OpenOLATStatisticsWebService implements Sampler {
* @return The statistics about OpenOLAT
*/
@GET
+ @Operation(summary = "Return the statistics about OpenOLAT", description = "Return the statistics about OpenOLAT, users count, courses count...")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The version of the instance", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = OpenOLATStatisticsVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = OpenOLATStatisticsVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient") })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getStatistics() {
OpenOLATStatisticsVO stats = new OpenOLATStatisticsVO();
@@ -92,6 +104,12 @@ public class OpenOLATStatisticsWebService implements Sampler {
@Tag(name = "Users")
@GET
@Path("users")
+ @Operation(summary = "Return the statistics about OpenOLAT users", description = "Return the statistics about OpenOLAT users")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The version of the instance", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = UserStatisticsVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = UserStatisticsVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient") })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getUserStatistics() {
UserStatisticsVO stats = getUserStatisticsVO();
@@ -111,6 +129,12 @@ public class OpenOLATStatisticsWebService implements Sampler {
@Tag(name = "Repo")
@GET
@Path("repository")
+ @Operation(summary = "Return the statistics about the repository", description = "Return the statistics about the repository, courses count, published courses... ")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The version of the instance", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = RepositoryStatisticsVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = RepositoryStatisticsVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient") })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getRepositoryStatistics() {
RepositoryStatisticsVO stats = getRepositoryStatisticsVO();
@@ -128,6 +152,12 @@ public class OpenOLATStatisticsWebService implements Sampler {
* @return The statistics about the indexer
*/
@Path("indexer")
+ @Operation(summary = "Return the statistics about the repository", description = "Return the statistics about the repository, courses count, published courses... ")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The version of the instance", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = IndexerStatisticsVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = IndexerStatisticsVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient") })
public IndexerWebService getIndexerStatistics() {
return indexerWebService;
}
@@ -144,6 +174,12 @@ public class OpenOLATStatisticsWebService implements Sampler {
*/
@GET
@Path("sessions")
+ @Operation(summary = "Return some statistics about session", description = "Return some statistics about session")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The version of the instance", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = SessionsVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = SessionsVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient") })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getSessions() {
SessionsVO vo = getSessionsVO();
@@ -162,6 +198,12 @@ public class OpenOLATStatisticsWebService implements Sampler {
*/
@GET
@Path("tasks")
+ @Operation(summary = "Return some statistics about long running tasks", description = "Return some statistics about long running tasks")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "A short summary about sessions", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = TasksVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = TasksVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient") })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getTasks() {
TasksVO vo = getTasksVO();
diff --git a/src/main/java/org/olat/restapi/system/RuntimeWebService.java b/src/main/java/org/olat/restapi/system/RuntimeWebService.java
index 0def5549699..78b870730a9 100644
--- a/src/main/java/org/olat/restapi/system/RuntimeWebService.java
+++ b/src/main/java/org/olat/restapi/system/RuntimeWebService.java
@@ -40,6 +40,12 @@ import org.olat.restapi.system.vo.MemoryStatisticsVO;
import org.olat.restapi.system.vo.RuntimeStatisticsVO;
import org.olat.restapi.system.vo.ThreadStatisticsVO;
+import io.swagger.v3.oas.annotations.Operation;
+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;
+
/**
*
* @author srosse, stephane.rosse@frentix.com, http://www.frentix.com
@@ -65,6 +71,14 @@ public class RuntimeWebService {
* @return The informations about runtime, uptime, classes loaded, memory summary...
*/
@GET
+ @Operation(summary = "Return the statistics about runtime", description = "Return the statistics about runtime: uptime, classes loaded, memory\n" +
+ " summary, threads count...")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The version of the instance", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = RuntimeStatisticsVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = RuntimeStatisticsVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The course not found") })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getSystemSummaryVO() {
RuntimeStatisticsVO stats = new RuntimeStatisticsVO();
@@ -94,6 +108,13 @@ public class RuntimeWebService {
*/
@GET
@Path("memory")
+ @Operation(summary = "Return the statistics about memory", description = "Return the statistics about memory")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The version of the instance", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = MemoryStatisticsVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = MemoryStatisticsVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The course not found") })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getMemoryStatistics() {
MemoryStatisticsVO stats = getMemoryStatisticsVO();
@@ -113,6 +134,13 @@ public class RuntimeWebService {
*/
@GET
@Path("threads")
+ @Operation(summary = "Return the statistics about threads", description = "Return the statistics about threads")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The version of the instance", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = ThreadStatisticsVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = ThreadStatisticsVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The course not found") })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getThreadStatistics() {
ThreadStatisticsVO stats = getThreadStatisticsVO();
@@ -131,6 +159,13 @@ public class RuntimeWebService {
*/
@GET
@Path("classes")
+ @Operation(summary = "Return some informations about the number of Java classes", description = "Return some informations about the number of Java classes...")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "A short summary of the number of classes", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = ClasseStatisticsVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = ClasseStatisticsVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The course not found") })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getCompilationXml() {
ClasseStatisticsVO stats = getClasseStatisticsVO();
diff --git a/src/main/java/org/olat/restapi/system/StatusWebservice.java b/src/main/java/org/olat/restapi/system/StatusWebservice.java
index 886834bfaa9..0b94e434de6 100644
--- a/src/main/java/org/olat/restapi/system/StatusWebservice.java
+++ b/src/main/java/org/olat/restapi/system/StatusWebservice.java
@@ -50,6 +50,12 @@ import org.olat.properties.Property;
import org.olat.properties.PropertyManager;
import org.olat.restapi.system.vo.StatusVO;
+import io.swagger.v3.oas.annotations.Operation;
+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;
+
/**
*
@@ -77,6 +83,13 @@ public class StatusWebservice {
* @return The informations about runtime, uptime, classes loaded, memory summary...
*/
@GET
+ @Operation(summary = "Return the statistics about runtime", description = "Return the statistics about runtime: uptime, classes loaded, memory\n" +
+ " summary, threads count...")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The version of the instance", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = StatusVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = StatusVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient") })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getSystemSummaryVO() {
StatusVO stats = new StatusVO();
diff --git a/src/main/java/org/olat/restapi/system/SystemWebService.java b/src/main/java/org/olat/restapi/system/SystemWebService.java
index 3a60b0c90f9..35bdd87bce0 100644
--- a/src/main/java/org/olat/restapi/system/SystemWebService.java
+++ b/src/main/java/org/olat/restapi/system/SystemWebService.java
@@ -45,6 +45,11 @@ import org.olat.restapi.system.vo.EnvironmentInformationsVO;
import org.olat.restapi.system.vo.ReleaseInfosVO;
import org.springframework.stereotype.Component;
+import io.swagger.v3.oas.annotations.Operation;
+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.tags.Tag;
/**
@@ -79,6 +84,12 @@ public class SystemWebService {
*/
@GET
@Path("environment")
+ @Operation(summary = "Return some informations about the environment", description = "Return some informations about the environment")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "A short summary of the number of classes", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = EnvironmentInformationsVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = EnvironmentInformationsVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient")})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getEnvironnementXml(@Context HttpServletRequest request) {
if(!isAdminOrSystemAdmin(request)) {
@@ -102,6 +113,12 @@ public class SystemWebService {
*/
@GET
@Path("release")
+ @Operation(summary = "Return the version of the instance", description = "Return the version of the instance")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The version of the instance", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = ReleaseInfosVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = ReleaseInfosVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient")})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getReleaseInfos(@Context HttpServletRequest request) {
if(!isAdminOrSystemAdmin(request)) {
@@ -123,6 +140,12 @@ public class SystemWebService {
}
@Path("monitoring")
+ @Operation(summary = "Return the version of the instance", description = "Return the version of the instance")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The version of the instance", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = MonitoringWebService.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = MonitoringWebService.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient")})
public MonitoringWebService getImplementedProbes(@Context HttpServletRequest request) {
if(!isMonitoringEnabled() && !isAdminOrSystemAdmin(request)) {
return null;
@@ -131,6 +154,12 @@ public class SystemWebService {
}
@Path("indexer")
+ @Operation(summary = "Return the version of the instance", description = "Return the version of the instance")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The version of the instance", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = IndexerWebService.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = IndexerWebService.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient")})
public IndexerWebService getIndexer(@Context HttpServletRequest request) {
if(!isAdminOrSystemAdmin(request)) {
return null;
@@ -139,6 +168,12 @@ public class SystemWebService {
}
@Path("notifications")
+ @Operation(summary = "Return the version of the instance", description = "Return the version of the instance")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The version of the instance", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = NotificationsAdminWebService.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = NotificationsAdminWebService.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient")})
public NotificationsAdminWebService getNotifications(@Context HttpServletRequest request) {
if(!isAdminOrSystemAdmin(request)) {
return null;
diff --git a/src/main/java/org/olat/user/restapi/IdentityToIdentityRelationsWebService.java b/src/main/java/org/olat/user/restapi/IdentityToIdentityRelationsWebService.java
index 6b453756d8f..11f0d4b317d 100644
--- a/src/main/java/org/olat/user/restapi/IdentityToIdentityRelationsWebService.java
+++ b/src/main/java/org/olat/user/restapi/IdentityToIdentityRelationsWebService.java
@@ -44,6 +44,13 @@ import org.olat.core.CoreSpringFactory;
import org.olat.core.id.Identity;
import org.springframework.beans.factory.annotation.Autowired;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+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;
+
/**
* The access permission is done by UserWebService.
*
@@ -79,6 +86,12 @@ public class IdentityToIdentityRelationsWebService {
*/
@GET
@Path("source")
+ @Operation(summary = "List of relations from the specified user to others", description = "List of relations from the specified user to others")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The list of relation from the specified user", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = IdentityToIdentityRelationVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = IdentityToIdentityRelationVO.class))) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient") })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getRelationsAsSource() {
List<IdentityToIdentityRelation> relations = identityRelationshipService.getRelationsAsSource(identity);
@@ -99,6 +112,12 @@ public class IdentityToIdentityRelationsWebService {
*/
@GET
@Path("target")
+ @Operation(summary = "List of relations to the specified user from others", description = "List of relations to the specified user from others")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The list of relation to the specified user", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = IdentityToIdentityRelationVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = IdentityToIdentityRelationVO.class))) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient") })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getRelationsAsTarget() {
RelationSearchParams searchParams = new RelationSearchParams();
@@ -123,6 +142,12 @@ public class IdentityToIdentityRelationsWebService {
* @return The new persisted <code>relation</code>
*/
@PUT
+ @Operation(summary = "Creates and persists a new relation entity", description = "Creates and persists a new relation entity")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The persisted relation", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = IdentityToIdentityRelationVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = IdentityToIdentityRelationVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient") })
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response putRelation(IdentityToIdentityRelationVO relationRoleVo) {
@@ -145,6 +170,12 @@ public class IdentityToIdentityRelationsWebService {
* @return The new persisted <code>relation</code>
*/
@POST
+ @Operation(summary = "Creates and persists a new relation entity", description = "Creates and persists a new relation entity")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The persisted relation", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = IdentityToIdentityRelationVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = IdentityToIdentityRelationVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient") })
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response postRelation(IdentityToIdentityRelationVO relationRoleVo) {
@@ -165,6 +196,10 @@ public class IdentityToIdentityRelationsWebService {
*/
@DELETE
@Path("{relationKey}")
+ @Operation(summary = "Delete a relation entity", description = "Deletes a relation entity")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The relation"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient") })
public Response deleteRelation(@PathParam("relationKey") Long relationKey) {
IdentityToIdentityRelation relation = identityRelationshipService.getRelation(relationKey);
if(relation == null) {
diff --git a/src/main/java/org/olat/user/restapi/OrganisationTypesWebService.java b/src/main/java/org/olat/user/restapi/OrganisationTypesWebService.java
index 96989e69663..c23f95b95a2 100644
--- a/src/main/java/org/olat/user/restapi/OrganisationTypesWebService.java
+++ b/src/main/java/org/olat/user/restapi/OrganisationTypesWebService.java
@@ -21,6 +21,7 @@ package org.olat.user.restapi;
import static org.olat.restapi.security.RestSecurityHelper.getRoles;
+
import java.util.ArrayList;
import java.util.List;
import java.util.Set;
@@ -48,6 +49,13 @@ import org.olat.core.id.Roles;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+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;
+
/**
*
* Initial date: 14 mai 2018<br>
@@ -73,6 +81,12 @@ public class OrganisationTypesWebService {
* @return An array of organization types
*/
@GET
+ @Operation(summary = "List of organizations types", description = "List of organizations types")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The list of all organization types in the OpenOLAT system", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = OrganisationTypeVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = OrganisationTypeVO.class))) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient") })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getOrganisations(@Context HttpServletRequest httpRequest) {
if(!isAdministrator(httpRequest)) {
@@ -101,6 +115,13 @@ public class OrganisationTypesWebService {
* @return The new persisted <code>organization type</code>
*/
@PUT
+ @Operation(summary = "Creates and persists a new organization type entity", description = "Creates and persists a new organization type entity")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "Creates and persists a new organization type entity", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = OrganisationTypeVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = OrganisationTypeVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "406", description = "application/xml, application/json")})
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response putOrganisationType(OrganisationTypeVO organisationType, @Context HttpServletRequest httpRequest) {
@@ -128,6 +149,13 @@ public class OrganisationTypesWebService {
* @return The merged <code>organization type</code>
*/
@POST
+ @Operation(summary = "Updates a new organization type entity", description = "Updates a new organization type entity")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The merged organization type", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = OrganisationTypeVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = OrganisationTypeVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "406", description = "application/xml, application/json")})
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response postOrganisationType(OrganisationTypeVO organisationType, @Context HttpServletRequest httpRequest) {
@@ -158,6 +186,14 @@ public class OrganisationTypesWebService {
*/
@POST
@Path("{organisationTypeKey}")
+ @Operation(summary = "Updates a new organization type entity", description = "Updates a new organization type entity. The primary key is taken from\n" +
+ " the URL. The organization type object can be \"primary key free\"")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The merged type organization", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = OrganisationTypeVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = OrganisationTypeVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "406", description = "application/xml, application/json")})
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response postOrganisation(@PathParam("organisationTypeKey") Long organisationTypeKey, OrganisationTypeVO organisationType,
@@ -207,6 +243,12 @@ public class OrganisationTypesWebService {
*/
@GET
@Path("{organisationTypeKey}")
+ @Operation(summary = "Get a specific organization type", description = "Get a specific organization type")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The organization type", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = OrganisationTypeVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = OrganisationTypeVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient")})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getOrganisations(@PathParam("organisationTypeKey") Long organisationTypeKey,
@Context HttpServletRequest httpRequest) {
@@ -236,6 +278,13 @@ public class OrganisationTypesWebService {
* @return An array of organization types
*/
@GET
+ @Operation(summary = "Get the allowed sub-types of a specified organization type", description = "Get the allowed sub-types of a specified organization type")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "An array of organization types", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = OrganisationTypeVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = OrganisationTypeVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "401", description = "The organization type was not found")})
@Path("{organisationTypeKey}/allowedSubTypes")
@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
public Response getAllowedSubTypes(@PathParam("organisationTypeKey") Long organisationTypeKey, @Context HttpServletRequest httpRequest) {
@@ -272,6 +321,13 @@ public class OrganisationTypesWebService {
*/
@PUT
@Path("{organisationTypeKey}/allowedSubTypes/{subTypeKey}")
+ @Operation(summary = "Add a sub-type", description = "Add a sub-type to a specified organization type")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The sub type was added to the allowed sub types", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = OrganisationTypeVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = OrganisationTypeVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "401", description = "The organization type was not found")})
@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
public Response allowSubTaxonomyLevelType(@PathParam("organisationTypeKey") Long organisationTypeKey, @PathParam("subTypeKey") Long subTypeKey,
@Context HttpServletRequest httpRequest) {
@@ -302,6 +358,11 @@ public class OrganisationTypesWebService {
*/
@DELETE
@Path("{organisationTypeKey}/allowedSubTypes/{subTypeKey}")
+ @Operation(summary = "Remove a sub-type", description = "Remove a sub-type to a specified organization type")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The sub type was removed successfully"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "401", description = "The organization type was not found")})
public Response disalloweSubTaxonomyLevelType(@PathParam("organisationTypeKey") Long organisationTypeKey, @PathParam("subTypeKey") Long subTypeKey,
@Context HttpServletRequest httpRequest) {
if(!isAdministrator(httpRequest)) {
diff --git a/src/main/java/org/olat/user/restapi/OrganisationsWebService.java b/src/main/java/org/olat/user/restapi/OrganisationsWebService.java
index 25973b132ae..444d807a416 100644
--- a/src/main/java/org/olat/user/restapi/OrganisationsWebService.java
+++ b/src/main/java/org/olat/user/restapi/OrganisationsWebService.java
@@ -61,8 +61,13 @@ import org.olat.restapi.support.vo.RepositoryEntryVO;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+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.tags.Tag;
-
/**
*
* Initial date: 14 mai 2018<br>
@@ -94,6 +99,9 @@ public class OrganisationsWebService {
*/
@GET
@Path("version")
+ @Operation(summary = "The version of the User Web Service", description = "The version of the User Web Service")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The version of this specific Web Service") })
@Produces(MediaType.TEXT_PLAIN)
public Response getVersion() {
return Response.ok(VERSION).build();
@@ -112,6 +120,12 @@ public class OrganisationsWebService {
* @return An array of organizations
*/
@GET
+ @Operation(summary = "List of organizations flat", description = "List of organizations flat")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The list of all organization in the OpenOLAT system", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = OrganisationVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = OrganisationVO.class))) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient") })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getOrganisations(@Context HttpServletRequest httpRequest) {
if(!isAdministrator(httpRequest)) {
@@ -140,6 +154,12 @@ public class OrganisationsWebService {
* @return The new persisted <code>organization</code>
*/
@PUT
+ @Operation(summary = "Creates and persists a new organization entity", description = "Creates and persists a new organization entity")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The persisted organization", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = OrganisationVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = OrganisationVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient") })
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response putOrganisation(OrganisationVO organisation, @Context HttpServletRequest httpRequest) {
@@ -167,6 +187,13 @@ public class OrganisationsWebService {
* @return The merged <code>organization</code>
*/
@POST
+ @Operation(summary = "Updates a new organization entity", description = "Updates a new organization entity")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The merged organization", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = OrganisationVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = OrganisationVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "406", description = "application/xml, application/json")})
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response postOrganisation(OrganisationVO organisation, @Context HttpServletRequest httpRequest) {
@@ -193,6 +220,12 @@ public class OrganisationsWebService {
*/
@GET
@Path("membership/{role}/{identityKey}")
+ @Operation(summary = "Get the organizations", description = "Get the organizations where the specified user has the role")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The list of organizations", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = OrganisationVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = OrganisationVO.class))) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient")})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getMemberships(@PathParam("role") String role, @PathParam("identityKey") Long identityKey,
@QueryParam("withInheritance") Boolean withInheritance, @Context HttpServletRequest httpRequest) {
@@ -228,6 +261,12 @@ public class OrganisationsWebService {
*/
@GET
@Path("{organisationKey}")
+ @Operation(summary = "Get a specific organization", description = "Get a specific organization")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The list of all organizations in the OpenOLAT system", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = OrganisationVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = OrganisationVO.class))) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient")})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getOrganisation(@PathParam("organisationKey") Long organisationKey, @Context HttpServletRequest httpRequest) {
if(!isAdministrator(httpRequest)) {
@@ -241,6 +280,12 @@ public class OrganisationsWebService {
@GET
@Path("{organisationKey}/entries")
+ @Operation(summary = "Get entries", description = "Get entries of a specific organization")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The list of all entries in the organization system", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = RepositoryEntryVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = RepositoryEntryVO.class))) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient")})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getRepositoryEntriesInOrganisation(@PathParam("organisationKey") Long organisationKey, @Context HttpServletRequest httpRequest) {
if(!isAdministrator(httpRequest)) {
@@ -275,6 +320,13 @@ public class OrganisationsWebService {
*/
@POST
@Path("{organisationKey}")
+ @Operation(summary = "Updates a new organization entity", description = "Updates a new organization entity. the primary key is taken from\n" +
+ " the url. The organization object can be \"primary key free\"")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The merged organization", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = OrganisationVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = OrganisationVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient")})
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response postOrganisation(@PathParam("organisationKey") Long organisationKey, OrganisationVO organisation,
@@ -355,6 +407,13 @@ public class OrganisationsWebService {
*/
@GET
@Path("{organisationKey}/{role}")
+ @Operation(summary = "Updates a new organization entity", description = "Updates a new organization entity. the primary key is taken from\n" +
+ " the url. The organization object can be \"primary key free\"")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The merged organization", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = OrganisationVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = OrganisationVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient")})
public Response getMembers(@PathParam("organisationKey") Long organisationKey, @PathParam("role") String role,
@Context HttpServletRequest httpRequest) {
if(!isAdministrator(httpRequest)) {
@@ -395,6 +454,12 @@ public class OrganisationsWebService {
*/
@PUT
@Path("{organisationKey}/{role}/{identityKey}")
+ @Operation(summary = "Make the specified user a member of the specified organization", description = "Make the specified user a member of the specified organization\n" +
+ " with the specified role")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The membership was added"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The organization or the identity was not found") })
public Response putMember(@PathParam("organisationKey") Long organisationKey, @PathParam("role") String role,
@PathParam("identityKey") Long identityKey, @QueryParam("inheritanceMode") String inheritanceMode,
@Context HttpServletRequest httpRequest) {
@@ -443,6 +508,12 @@ public class OrganisationsWebService {
*/
@PUT
@Path("{organisationKey}/{role}")
+ @Operation(summary = "Add a membership to the specified curriculum element", description = "Add a membership to the specified curriculum element")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The membership was persisted"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The curriculum element or the identity was not found"),
+ @ApiResponse(responseCode = "409", description = "The role is not allowed")})
public Response putMembers(@PathParam("organisationKey") Long organisationKey, @PathParam("role") String role,
@QueryParam("inheritanceMode") String inheritanceMode, UserVO[] members,
@Context HttpServletRequest httpRequest) {
@@ -488,6 +559,11 @@ public class OrganisationsWebService {
*/
@DELETE
@Path("{organisationKey}/{role}/{identityKey}")
+ @Operation(summary = "Remove the membership", description = "Remove the membership of the identity from the specified organization and role")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The membership was removed"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The curriculum element or the identity was not found")})
public Response deleteMember(@PathParam("organisationKey") Long organisationKey, @PathParam("role") String role,
@PathParam("identityKey") Long identityKey, @Context HttpServletRequest httpRequest) {
if(!isAdministrator(httpRequest)) {
diff --git a/src/main/java/org/olat/user/restapi/RelationRolesWebService.java b/src/main/java/org/olat/user/restapi/RelationRolesWebService.java
index 72469c5366d..0438f2b1dc7 100644
--- a/src/main/java/org/olat/user/restapi/RelationRolesWebService.java
+++ b/src/main/java/org/olat/user/restapi/RelationRolesWebService.java
@@ -20,6 +20,7 @@
package org.olat.user.restapi;
import java.util.Collections;
+
import java.util.List;
import java.util.stream.Collectors;
@@ -46,6 +47,12 @@ import org.olat.restapi.security.RestSecurityHelper;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+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.tags.Tag;
/**
@@ -73,6 +80,9 @@ public class RelationRolesWebService {
*/
@GET
@Path("version")
+ @Operation(summary = "The version of the Web Service", description = "The version of the Web Service")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The version of this specific Web Service") })
@Produces(MediaType.TEXT_PLAIN)
public Response getVersion() {
return Response.ok(VERSION).build();
@@ -91,6 +101,12 @@ public class RelationRolesWebService {
*/
@GET
@Path("roles")
+ @Operation(summary = "List of relation roles", description = "List of relation roles")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The list of all relation roles in the OpenOLAT system", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = RelationRoleVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = RelationRoleVO.class))) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient") })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getRoles(@Context HttpServletRequest httpRequest) {
if(!isAdministrator(httpRequest)) {
@@ -120,6 +136,13 @@ public class RelationRolesWebService {
*/
@PUT
@Path("roles")
+ @Operation(summary = "Creates and persists a new relation role entity", description = "Creates and persists a new relation role entity")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The persisted relation role", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = RelationRoleVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = RelationRoleVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "406", description = "application/xml, application/json")})
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response putRelationRole(RelationRoleVO relationRoleVo, @Context HttpServletRequest httpRequest) {
@@ -148,6 +171,13 @@ public class RelationRolesWebService {
*/
@POST
@Path("roles")
+ @Operation(summary = "Update a relation role entity", description = "Updates a relation role entity")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The merged relation role", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = RelationRoleVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = RelationRoleVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "406", description = "application/xml, application/json")})
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response postRelationRole(RelationRoleVO relationRoleVo, @Context HttpServletRequest httpRequest) {
@@ -176,6 +206,13 @@ public class RelationRolesWebService {
*/
@POST
@Path("roles/{relationRoleKey}")
+ @Operation(summary = "Update a relation role entity", description = "Updates a relation role entity")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The merged relation role", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = RelationRoleVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = RelationRoleVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "406", description = "application/xml, application/json")})
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response postRelationRole(RelationRoleVO relationRoleVo, @PathParam("relationRoleKey") Long relationRoleKey,
@@ -216,6 +253,11 @@ public class RelationRolesWebService {
@DELETE
@Path("roles/{relationRoleKey}")
+ @Operation(summary = "Remove role", description = "Remove a role")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The role has been removed"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "Role not found")})
public Response deleteRelationRole(@PathParam("relationRoleKey") Long relationRoleKey, @Context HttpServletRequest httpRequest) {
if(!isAdministrator(httpRequest)) {
return Response.serverError().status(Status.UNAUTHORIZED).build();
diff --git a/src/main/java/org/olat/user/restapi/UserAuthenticationWebService.java b/src/main/java/org/olat/user/restapi/UserAuthenticationWebService.java
index ee29e8c124b..c696ca9202f 100644
--- a/src/main/java/org/olat/user/restapi/UserAuthenticationWebService.java
+++ b/src/main/java/org/olat/user/restapi/UserAuthenticationWebService.java
@@ -21,6 +21,7 @@ package org.olat.user.restapi;
import static org.olat.restapi.security.RestSecurityHelper.getIdentity;
+
import java.util.List;
import javax.servlet.http.HttpServletRequest;
@@ -53,6 +54,12 @@ import org.olat.restapi.support.vo.ErrorVO;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+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.tags.Tag;
/**
@@ -83,6 +90,9 @@ public class UserAuthenticationWebService {
*/
@GET
@Path("version")
+ @Operation(summary = "The version of the User Authentication Web Service", description = "The version of the User Authentication Web Service")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The version of this specific Web Service") })
@Produces(MediaType.TEXT_PLAIN)
public Response getVersion() {
return Response.ok(VERSION).build();
@@ -101,6 +111,13 @@ public class UserAuthenticationWebService {
* @return
*/
@GET
+ @Operation(summary = "Returns all user authentications", description = "Returns all user authentications")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The list of all users in the OLAT system", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = AuthenticationVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = AuthenticationVO.class))) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The identity not found") })
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getAuthenticationTokenList(@PathParam("username") String username, @Context HttpServletRequest request) {
Identity identity = securityManager.findIdentityByName(username);
@@ -140,6 +157,15 @@ public class UserAuthenticationWebService {
* @return the saved authentication
*/
@PUT
+ @Operation(summary = "Creates and persists an authentication", description = "Creates and persists an authentication")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The saved authentication", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = AuthenticationVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = AuthenticationVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The identity not found") ,
+ @ApiResponse(responseCode = "406", description = "Cannot create the authentication for an unkown reason"),
+ @ApiResponse(responseCode = "409", description = "Cannot create the authentication because the authentication username is already used by someone else within the same provider") })
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response create(@PathParam("username") String username, AuthenticationVO authenticationVO, @Context HttpServletRequest request) {
@@ -190,6 +216,11 @@ public class UserAuthenticationWebService {
*/
@DELETE
@Path("{authKey}")
+ @Operation(summary = "Deletes an authentication from the system", description = "Deletes an authentication from the system")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The authentication successfully deleted"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The identity not found") })
public Response delete(@PathParam("username") String username, @PathParam("authKey") Long authKey, @Context HttpServletRequest request) {
Identity identity = securityManager.findIdentityByName(username);
if(identity == null) {
@@ -223,6 +254,12 @@ public class UserAuthenticationWebService {
*/
@POST
@Path("password")
+ @Operation(summary = "Change the password of a user", description = "Change the password of a user")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The password successfully changed"),
+ @ApiResponse(responseCode = "304", description = "The password was not changed"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The identity or the authentication not found") })
public Response changePassword(@PathParam("username") String username, @FormParam("newPassword") String newPassword,
@Context HttpServletRequest request) {
Identity doer = getIdentity(request);
diff --git a/src/main/java/org/olat/user/restapi/UserCoursesWebService.java b/src/main/java/org/olat/user/restapi/UserCoursesWebService.java
index f78d12d46e0..1ebe8fa04c8 100644
--- a/src/main/java/org/olat/user/restapi/UserCoursesWebService.java
+++ b/src/main/java/org/olat/user/restapi/UserCoursesWebService.java
@@ -20,6 +20,7 @@
package org.olat.user.restapi;
import java.util.ArrayList;
+
import java.util.Collections;
import java.util.List;
@@ -49,6 +50,13 @@ import org.olat.restapi.support.vo.CourseVO;
import org.olat.restapi.support.vo.CourseVOes;
import org.springframework.beans.factory.annotation.Autowired;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+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;
+
/**
*
* @author srosse, stephane.rosse@frentix.com, http://www.frentix.com
@@ -84,6 +92,12 @@ public class UserCoursesWebService {
*/
@GET
@Path("my")
+ @Operation(summary = "Retrieves the list of \"My entries\"", description = "Retrieves the list of \"My entries\" but limited to courses")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The courses", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = CourseVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = CourseVO.class))) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient")})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getMyCourses(@QueryParam("start") @DefaultValue("0") Integer start,
@QueryParam("limit") @DefaultValue("25") Integer limit, @Context HttpServletRequest httpRequest,
@@ -120,6 +134,12 @@ public class UserCoursesWebService {
*/
@GET
@Path("teached")
+ @Operation(summary = "Retrieves the list of \"My supervised courses\"", description = "Retrieves the list of \"My supervised courses\" but limited to courses")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The courses", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = CourseVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = CourseVO.class))) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient")})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getTeachedCourses(@QueryParam("start") @DefaultValue("0") Integer start,
@QueryParam("limit") @DefaultValue("25") Integer limit, @Context HttpServletRequest httpRequest,
@@ -156,6 +176,12 @@ public class UserCoursesWebService {
*/
@GET
@Path("favorite")
+ @Operation(summary = "Retrieves the list of my favorite courses", description = "Retrieves the list of my favorite courses")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The courses", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = CourseVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = CourseVO.class))) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient")})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getFavoritCourses(@QueryParam("start") @DefaultValue("0") Integer start,
@QueryParam("limit") @DefaultValue("25") Integer limit, @Context HttpServletRequest httpRequest,
diff --git a/src/main/java/org/olat/user/restapi/UserFoldersWebService.java b/src/main/java/org/olat/user/restapi/UserFoldersWebService.java
index b30a860a85b..3afa7544abd 100644
--- a/src/main/java/org/olat/user/restapi/UserFoldersWebService.java
+++ b/src/main/java/org/olat/user/restapi/UserFoldersWebService.java
@@ -20,6 +20,7 @@
package org.olat.user.restapi;
import static org.olat.restapi.security.RestSecurityHelper.getIdentity;
+
import static org.olat.restapi.security.RestSecurityHelper.getRoles;
import java.util.ArrayList;
@@ -69,9 +70,17 @@ import org.olat.group.BusinessGroup;
import org.olat.group.BusinessGroupService;
import org.olat.group.model.SearchBusinessGroupParams;
import org.olat.restapi.group.LearningGroupWebService;
+import org.olat.restapi.support.vo.FileVO;
import org.olat.restapi.support.vo.FolderVO;
import org.olat.restapi.support.vo.FolderVOes;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+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;
+
/**
*
* Description:<br>
@@ -121,6 +130,12 @@ public class UserFoldersWebService {
* @return The files
*/
@Path("group/{groupKey}")
+ @Operation(summary = "Retrieve the folder of a group", description = "Retrieves the folder of a group")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The files", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = FileVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = FileVO.class))) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient") })
public VFSWebservice getGroupFolder(@PathParam("groupKey") Long groupKey, @Context HttpServletRequest request) {
if(groupKey == null) {
throw new WebApplicationException( Response.serverError().status(Status.NOT_FOUND).build());
@@ -142,6 +157,12 @@ public class UserFoldersWebService {
* @return The files
*/
@Path("course/{courseKey}/{courseNodeId}")
+ @Operation(summary = "Retrieves the folder of a course building block", description = "Retrieves the folder of a course building block")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The files", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = FileVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = FileVO.class))) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient") })
public VFSWebservice getCourseFolder(@PathParam("courseKey") Long courseKey, @PathParam("courseNodeId") String courseNodeId,
@Context HttpServletRequest request) {
return new BCWebService().getVFSWebService(courseKey, courseNodeId, request);
@@ -161,6 +182,14 @@ public class UserFoldersWebService {
* @return The folders
*/
@GET
+ @Operation(summary = "Retrieves a list of folders on a user base", description = "Retrieves a list of folders on a user base. All folders of groups \n" +
+ " where the user is participant/tutor + all folders in course where\n" +
+ " the user is a participant (owner, tutor or participant)")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The folders", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = FolderVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = FolderVO.class))) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient") })
@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
public Response getFolders(@Context HttpServletRequest httpRequest) {
diff --git a/src/main/java/org/olat/user/restapi/UserWebService.java b/src/main/java/org/olat/user/restapi/UserWebService.java
index 2159fcfcac4..e70174d9674 100644
--- a/src/main/java/org/olat/user/restapi/UserWebService.java
+++ b/src/main/java/org/olat/user/restapi/UserWebService.java
@@ -20,6 +20,7 @@
package org.olat.user.restapi;
import static org.olat.restapi.security.RestSecurityHelper.getIdentity;
+
import static org.olat.restapi.security.RestSecurityHelper.getLocale;
import static org.olat.restapi.security.RestSecurityHelper.getRoles;
import static org.olat.restapi.security.RestSecurityHelper.getUserRequest;
@@ -94,6 +95,12 @@ import org.olat.user.propertyhandlers.UserPropertyHandler;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+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.tags.Tag;
/**
@@ -142,6 +149,9 @@ public class UserWebService {
*/
@GET
@Path("version")
+ @Operation(summary = "The version of the User Web Service", description = "The version of the User Web Service")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The version of this specific Web Service")})
@Produces(MediaType.TEXT_PLAIN)
public Response getVersion() {
return Response.ok(VERSION).build();
@@ -174,6 +184,23 @@ public class UserWebService {
* @return An array of users
*/
@GET
+ @Operation(summary = "Search users and return them in a simple form ", description = "Search users and return them in a simple form (without user properties). User properties\n" +
+ " can be added two the query parameters. If the authUsername and the authProvider are set,\n" +
+ " the search is made only with these two parameters because they are sufficient to return\n" +
+ " a single user.<br>\n" +
+ " The search with login and user properties are made default with wild cards. If an exact\n" +
+ " match is needed, the parameter msut be quoted:<br>\n" +
+ " users?login=\"username\"<br>\n" +
+ " Don't forget the right escaping in the URL!<br>\n" +
+ " You can make a search with the user properties like this:<br>\n" +
+ " users?telMobile=39847592&login=test\n" +
+ " <br >/ The lookup is possible for authors, usermanagers and system administrators. Normal\n" +
+ " users are not allowed to use the lookup service.")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The list of all users in the OLAT system", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = UserVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = UserVO.class))) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient")})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getUserListQuery(@QueryParam("login") String login,
@QueryParam("authProvider") String authProvider, @QueryParam("authUsername") String authUsername,
@@ -241,6 +268,12 @@ public class UserWebService {
@GET
@Path("managed")
+ @Operation(summary = "Get managed Users", description = "Get managed Users")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "List of all managed users", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = ManagedUserVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = ManagedUserVO.class))) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient")})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response getManagedUsers(@Context HttpServletRequest httpRequest) {
if(!isUserManager(httpRequest)) {
@@ -276,6 +309,15 @@ public class UserWebService {
* @return the new persisted <code>User</code>
*/
@PUT
+ @Operation(summary = "Creates and persists a new user entity", description = "Creates and persists a new user entity")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The persisted user", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = UserVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = UserVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "406", description = "The list of errors", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = ErrorVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = ErrorVO.class))) })})
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response create(UserVO user, @Context HttpServletRequest request) {
@@ -362,6 +404,13 @@ public class UserWebService {
*/
@GET
@Path("{identityKey}/roles")
+ @Operation(summary = "Retrieve the roles", description = "Retrieves the roles of a user given its unique key identifier")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The user", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = RolesVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = RolesVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The identity not found")})
@Produces({MediaType.APPLICATION_XML ,MediaType.APPLICATION_JSON})
public Response getIdentityRoles(@PathParam("identityKey") Long identityKey, @Context HttpServletRequest request) {
if(!isUserManagerOf(identityKey, request)) {
@@ -390,6 +439,13 @@ public class UserWebService {
*/
@POST
@Path("{identityKey}/roles")
+ @Operation(summary = "Update the roles", description = "Update the roles of a user given its unique key identifier")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The user", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = RolesVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = RolesVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The identity not found")})
@Consumes({MediaType.APPLICATION_XML ,MediaType.APPLICATION_JSON})
@Produces({MediaType.APPLICATION_XML ,MediaType.APPLICATION_JSON})
public Response updateRoles(@PathParam("identityKey") Long identityKey, RolesVO roles, @Context HttpServletRequest request) {
@@ -429,6 +485,13 @@ public class UserWebService {
*/
@GET
@Path("{identityKey}/status")
+ @Operation(summary = "Retrieve the status", description = "Retrieves the status of a user given its unique key identifier")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The user", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = StatusVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = StatusVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The identity not found")})
@Produces({MediaType.APPLICATION_XML ,MediaType.APPLICATION_JSON})
public Response getStatus(@PathParam("identityKey") Long identityKey, @Context HttpServletRequest request) {
boolean isUserManager = isUserManagerOf(identityKey, request);
@@ -467,6 +530,20 @@ public class UserWebService {
*/
@POST
@Path("{identityKey}/status")
+ @Operation(summary = "Update the roles of a user", description = "Update the roles of a user given its unique key identifier:\n" +
+ " <ul>\n" +
+ " <li>1: Permanent user</li> \n" +
+ " <li>2: activ</li> \n" +
+ " <li>101: login denied</li> \n" +
+ " <li>199: deleted</li> \n" +
+ " </ul>\n" +
+ " ")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The user", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = StatusVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = StatusVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The identity not found")})
@Consumes({MediaType.APPLICATION_XML ,MediaType.APPLICATION_JSON})
@Produces({MediaType.APPLICATION_XML ,MediaType.APPLICATION_JSON})
public Response updateStatus(@PathParam("identityKey") Long identityKey, StatusVO status, @Context HttpServletRequest request) {
@@ -500,6 +577,13 @@ public class UserWebService {
*/
@GET
@Path("{identityKey}/preferences")
+ @Operation(summary = "Retrieve the preferences", description = "Retrieves the preferences of a user given its unique key identifier")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The preferences", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = PreferencesVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = PreferencesVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The identity not found")})
@Produces({MediaType.APPLICATION_XML ,MediaType.APPLICATION_JSON})
public Response getUserPreferences(@PathParam("identityKey") Long identityKey, @Context HttpServletRequest request) {
boolean isUserManager = isUserManagerOf(identityKey, request);
@@ -530,6 +614,13 @@ public class UserWebService {
*/
@POST
@Path("{identityKey}/preferences")
+ @Operation(summary = "Update the preferences", description = "Update the preferences of a user given its unique key identifier")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The user", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = PreferencesVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = PreferencesVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The identity not found")})
@Consumes({MediaType.APPLICATION_XML ,MediaType.APPLICATION_JSON})
@Produces({MediaType.APPLICATION_XML ,MediaType.APPLICATION_JSON})
public Response updatePreferences(@PathParam("identityKey") Long identityKey, PreferencesVO preferences, @Context HttpServletRequest request) {
@@ -577,6 +668,13 @@ public class UserWebService {
*/
@GET
@Path("{identityKey}")
+ @Operation(summary = "Retrieve a user", description = "Retrieves an user given its unique key identifier")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The user", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = UserVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = UserVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The identity not found")})
@Produces({MediaType.APPLICATION_XML ,MediaType.APPLICATION_JSON})
public Response findById(@PathParam("identityKey") Long identityKey, @QueryParam("withPortrait") @DefaultValue("false") Boolean withPortrait,
@Context HttpServletRequest httpRequest) {
@@ -591,6 +689,11 @@ public class UserWebService {
}
@Path("{identityKey}/folders")
+ @Operation(summary = "Retrieve folders", description = "Retrieves folders from a user given its unique key identifier")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The folders"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The identity not found")})
public UserFoldersWebService getFoldersWebService(@PathParam("identityKey") Long identityKey) {
Identity identity = securityManager.loadIdentityByKey(identityKey, false);
if(identity == null) {
@@ -600,6 +703,11 @@ public class UserWebService {
}
@Path("{identityKey}/courses")
+ @Operation(summary = "Retrieve courses", description = "Retrieves courses from a user given its unique key identifier")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The courses"),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The identity not found")})
public UserCoursesWebService getCoursesWebService(@PathParam("identityKey") Long identityKey,
@Context HttpServletRequest httpRequest) {
Identity identity = securityManager.loadIdentityByKey(identityKey, false);
@@ -626,6 +734,10 @@ public class UserWebService {
*/
@HEAD
@Path("{identityKey}/portrait")
+ @Operation(summary = "Retrieves the portrait of an user", description = "Retrieves the portrait of an user")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The portrait as image"),
+ @ApiResponse(responseCode = "404", description = "The identity or the portrait not found")})
@Produces({"image/jpeg","image/jpg",MediaType.APPLICATION_OCTET_STREAM})
public Response getPortraitHead(@PathParam("identityKey") Long identityKey) {
IdentityShort identity = securityManager.loadIdentityShortByKey(identityKey);
@@ -652,6 +764,10 @@ public class UserWebService {
*/
@HEAD
@Path("{identityKey}/portrait/{size}")
+ @Operation(summary = "Retrieves the portrait of an user", description = "Retrieves the portrait of an user")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The portrait as image"),
+ @ApiResponse(responseCode = "404", description = "The identity or the portrait not found")})
@Produces({"image/jpeg","image/jpg",MediaType.APPLICATION_OCTET_STREAM})
public Response getOriginalPortraitHead(@PathParam("identityKey") Long identityKey, @PathParam("size") String size) {
IdentityShort identity = securityManager.loadIdentityShortByKey(identityKey);
@@ -686,6 +802,10 @@ public class UserWebService {
*/
@GET
@Path("{identityKey}/portrait")
+ @Operation(summary = "Retrieves the portrait of an user", description = "Retrieves the portrait of an user")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The portrait as image"),
+ @ApiResponse(responseCode = "404", description = "The identity or the portrait not found")})
@Produces({"image/jpeg","image/jpg",MediaType.APPLICATION_OCTET_STREAM})
public Response getPortrait(@PathParam("identityKey") Long identityKey, @Context Request request) {
IdentityShort identity = securityManager.loadIdentityShortByKey(identityKey);
@@ -719,6 +839,11 @@ public class UserWebService {
*/
@POST
@Path("{identityKey}/portrait")
+ @Operation(summary = "Upload the portrait of an user", description = "Upload the portrait of an user")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The portrait as image"),
+ @ApiResponse(responseCode = "401", description = "Not authorized"),
+ @ApiResponse(responseCode = "404", description = "The identity or the portrait not found")})
@Consumes({MediaType.MULTIPART_FORM_DATA})
public Response postPortrait(@PathParam("identityKey") Long identityKey, @Context HttpServletRequest request) {
MultipartReader partsReader = null;
@@ -754,6 +879,10 @@ public class UserWebService {
*/
@DELETE
@Path("{identityKey}/portrait")
+ @Operation(summary = "Deletes the portrait of an user", description = "Deletes the portrait of an user")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The portrait deleted"),
+ @ApiResponse(responseCode = "401", description = "Not authorized")})
public Response deletePortrait(@PathParam("identityKey") Long identityKey, @Context HttpServletRequest request) {
Identity authIdentity = getUserRequest(request).getIdentity();
Identity identity = securityManager.loadIdentityByKey(identityKey, false);
@@ -801,6 +930,16 @@ public class UserWebService {
*/
@POST
@Path("{identityKey}")
+ @Operation(summary = "Update an user", description = "Update an user")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The user", content = {
+ @Content(mediaType = "application/json", schema = @Schema(implementation = UserVO.class)),
+ @Content(mediaType = "application/xml", schema = @Schema(implementation = UserVO.class)) }),
+ @ApiResponse(responseCode = "401", description = "The roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The identity not found"),
+ @ApiResponse(responseCode = "406", description = "The list of validation errors", content = {
+ @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = ErrorVO.class))),
+ @Content(mediaType = "application/xml", array = @ArraySchema(schema = @Schema(implementation = ErrorVO.class))) })})
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response update(@PathParam("identityKey") Long identityKey, UserVO user, @Context HttpServletRequest request) {
@@ -911,6 +1050,12 @@ public class UserWebService {
*/
@DELETE
@Path("{identityKey}")
+ @Operation(summary = "Delete an user from the system", description = "Delete an user from the system")
+ @ApiResponses({
+ @ApiResponse(responseCode = "200", description = "The user is removed from the group"),
+ @ApiResponse(responseCode = "401", description = "he roles of the authenticated user are not sufficient"),
+ @ApiResponse(responseCode = "404", description = "The identity not found"),
+ @ApiResponse(responseCode = "500", description = "Unknown problem while deleting, see olat.log")})
public Response delete(@PathParam("identityKey") Long identityKey, @Context HttpServletRequest request) {
Identity actingIdentity = getIdentity(request);
if(actingIdentity == null || !isUserManagerOf(identityKey, request)) {
--
GitLab