FXOLAT-296 : update the documentation of the REST API

src/main/java/org/olat/core/util/vfs/restapi/VFSWebservice.java

@@ -73,9 +73,9 @@ public class VFSWebservice {
 	
 	/**
 	 * Retrieves the version of the Folder Course Node Web Service.
-   * @response.representation.200.mediaType text/plain
-   * @response.representation.200.doc The version of this specific Web Service
-   * @response.representation.200.example 1.0
+	 * @response.representation.200.mediaType text/plain
+	 * @response.representation.200.doc The version of this specific Web Service
+	 * @response.representation.200.example 1.0
 	 * @return
 	 */
 	@GET
@@ -87,8 +87,8 @@ public class VFSWebservice {
 	
 	/**
 	 * This retrieves the files or a specific file in the root folder
-   * @response.representation.200.doc The list of files
-   * @response.representation.200.qname {http://www.example.com}linkVOes
+	 * @response.representation.200.doc The list of files
+	 * @response.representation.200.qname {http://www.example.com}linkVOes
 	 * @param uriInfo The uri infos
 	 * @param request The REST request
 	 * @return 
@@ -101,12 +101,12 @@ public class VFSWebservice {
 	
 	/**
 	 * This retrieves the files or a specific file in a folder
-   * @response.representation.200.doc The list of files or the file
-   * @response.representation.200.qname {http://www.example.com}linkVOes
-   * @param path the path to the folder
-   * @param uriInfo The uri infos
-   * @param request The REST request
-   * @return 
+	 * @response.representation.200.doc The list of files or the file
+	 * @response.representation.200.qname {http://www.example.com}linkVOes
+	 * @param path the path to the folder
+	 * @param uriInfo The uri infos
+	 * @param request The REST request
+	 * @return 
 	 */
 	@GET
 	@Path("{path:.*}")
@@ -118,10 +118,10 @@ public class VFSWebservice {
 	/**
 	 * Upload a file to the root folder or create a new folder. One of the two sets
 	 * of parameters must be set: foldername to create
-   * @response.representation.200.doc The link to the created file
-   * @response.representation.200.qname {http://www.example.com}linkVO
-   * @param foldername The name of the new folder (optional)
-   * @param filename The name of the file (optional)
+	 * @response.representation.200.doc The link to the created file
+	 * @response.representation.200.qname {http://www.example.com}linkVO
+	 * @param foldername The name of the new folder (optional)
+	 * @param filename The name of the file (optional)
 	 * @param file The content of the file (optional)
 	 * @param uriInfo The uri infos
 	 * @return The link to the created file
@@ -136,10 +136,10 @@ public class VFSWebservice {
 	
 	/**
 	 * Upload a file to the specified folder or create a new folder
-   * @response.representation.200.doc The link to the created file
-   * @response.representation.200.qname {http://www.example.com}linkVO
-   * @param foldername The name of the new folder (optional)
-   * @param filename The name of the file (optional)
+	 * @response.representation.200.doc The link to the created file
+	 * @response.representation.200.qname {http://www.example.com}linkVO
+	 * @param foldername The name of the new folder (optional)
+	 * @param filename The name of the file (optional)
 	 * @param file The content of the file (optional)
 	 * @param uriInfo The uri infos
 	 * @param path The path to the folder
@@ -156,10 +156,10 @@ public class VFSWebservice {
 	
 	/**
 	 * Upload a file to the root folder or create a new folder
-   * @response.representation.200.doc The link to the created file
-   * @response.representation.200.qname {http://www.example.com}linkVO
-   * @param foldername The name of the new folder (optional)
-   * @param filename The name of the file (optional)
+	 * @response.representation.200.doc The link to the created file
+	 * @response.representation.200.qname {http://www.example.com}linkVO
+	 * @param foldername The name of the new folder (optional)
+	 * @param filename The name of the file (optional)
 	 * @param file The content of the file (optional)
 	 * @param uriInfo The uri infos
 	 * @return The link to the created file
@@ -174,10 +174,10 @@ public class VFSWebservice {
 	
 	/**
 	 * Upload a file to the specified folder or create a new folder
-   * @response.representation.200.doc The link to the created file
-   * @response.representation.200.qname {http://www.example.com}linkVO
-   * @param foldername The name of the new folder (optional)
-   * @param filename The name of the file (optional)
+	 * @response.representation.200.doc The link to the created file
+	 * @response.representation.200.qname {http://www.example.com}linkVO
+	 * @param foldername The name of the new folder (optional)
+	 * @param filename The name of the file (optional)
 	 * @param file The content of the file (optional)
 	 * @param uriInfo The uri infos
 	 * @param path The path to the folder
@@ -194,8 +194,8 @@ public class VFSWebservice {
 	
 	/**
 	 * Create folders
-   * @response.representation.200.doc The link to the created file
-   * @response.representation.200.qname {http://www.example.com}linkVO
+	 * @response.representation.200.doc The link to the created file
+	 * @response.representation.200.qname {http://www.example.com}linkVO
 	 * @param uriInfo The uri infos
 	 * @param path The path to the folder
 	 * @return The link to the created file

src/main/java/org/olat/modules/fo/restapi/Examples.java

@@ -34,6 +34,8 @@ public class Examples {
 
 	public static final MessageVO SAMPLE_MESSAGEVO = new MessageVO();
 	public static final MessageVOes SAMPLE_MESSAGEVOes = new MessageVOes();
+	
+	public static final ForumVO SAMPLE_FORUMVO = new ForumVO();
   
   static {
   	SAMPLE_MESSAGEVO.setKey(380l);
@@ -42,5 +44,7 @@ public class Examples {
   	SAMPLE_MESSAGEVO.setBody("The content of the message");
   	SAMPLE_MESSAGEVOes.setMessages(new MessageVO[]{SAMPLE_MESSAGEVO});
   	SAMPLE_MESSAGEVOes.setTotalCount(1);
+  	
+  	SAMPLE_FORUMVO.setForumKey(28294l);
   }
 }

src/main/java/org/olat/modules/fo/restapi/ForumImportWebService.java

@@ -34,8 +34,7 @@ import org.olat.modules.fo.ForumManager;
 /**
  * 
  * Description:<br>
- * Web service to manage forum element. This implementation is
- * only for import.
+ * Web service to manage forums.
  * 
  * <P>
  * Initial Date:  26 aug. 2010 <br>
@@ -60,6 +59,11 @@ public class ForumImportWebService {
 		return Response.ok(VERSION).build();
 	}
 	
+	/**
+	 * Web service to manage a forum
+	 * @param forumKey The key of the forum
+	 * @return
+	 */
 	@Path("{forumKey}")
 	public ForumWebService getForumWebservice(@PathParam("forumKey") Long forumKey) {
 		ForumManager fom = ForumManager.getInstance();

src/main/java/org/olat/modules/fo/restapi/ForumWebService.java

@@ -74,8 +74,7 @@ import org.olat.restapi.support.vo.FileVO;
 /**
  * 
  * Description:<br>
- * Web service to manage forum element. This implementation is
- * only for import.
+ * Web service to manage a forum.
  * 
  * <P>
  * Initial Date:  20 apr. 2010 <br>
@@ -97,6 +96,16 @@ public class ForumWebService {
 		this.forum = forum;
 	}
 	
+	/**
+	 * Retrieves the forum.
+	 * @response.representation.200.qname {http://www.example.com}forumVO
+	 * @response.representation.200.mediaType application/xml, application/json
+	 * @response.representation.200.doc The root message of the thread
+	 * @response.representation.200.example {@link org.olat.modules.fo.restapi.Examples#SAMPLE_FORUMVO}
+	 * @response.representation.401.doc The roles of the authenticated user are not sufficient
+	 * @response.representation.404.doc The forum not found
+	 * @return The forum
+	 */
 	@GET
 	@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
 	public Response getForum() {
@@ -323,11 +332,11 @@ public class ForumWebService {
 
 	/**
 	 * Retrieves the attachments of the message
-	 * @response.representation.200.mediaType application/xml
-	 * @response.representation.200.doc The portrait as image
-   * @response.representation.404.doc The identity or the portrait not found
+	 * @response.representation.200.mediaType application/xml, application/json
+	 * @response.representation.200.doc The links to the attachments
+	 * @response.representation.404.doc The message not found
 	 * @param messageKey The key of the message
-	 * @param request The REST request
+	 * @param uriInfo The URI information
 	 * @return The attachments
 	 */
 	@GET
@@ -365,9 +374,10 @@ public class ForumWebService {
 	 * @response.representation.200.mediaType application/octet-stream
 	 * @response.representation.200.doc The portrait as image
    * @response.representation.404.doc The identity or the portrait not found
-	 * @param identityKey The identity key of the user being searched
+	 * @param messageKey The identity key of the user being searched
+	 * @param filename The name of the attachment
 	 * @param request The REST request
-	 * @return The image
+	 * @return The attachment
 	 */
 	@GET
 	@Path("posts/{messageKey}/attachments/{filename}")
@@ -407,6 +417,17 @@ public class ForumWebService {
 		return Response.serverError().status(Status.NOT_FOUND).build();
 	}
 	
+	/**
+	 * Upload the attachment of a message
+	 * @response.representation.200.mediaType application/json, application/xml
+	 * @response.representation.200.doc Ok
+	 * @response.representation.404.doc The identity or the portrait not found
+	 * @param messageKey The key of the message
+	 * @param filename The name of the attachment
+	 * @file file The attachment
+	 * @param request The HTTP request
+	 * @return Ok
+	 */
 	@POST
 	@Path("posts/{messageKey}/attachments")
 	@Consumes(MediaType.MULTIPART_FORM_DATA)

src/main/java/org/olat/notifications/restapi/NotificationsWebService.java

@@ -64,9 +64,10 @@ public class NotificationsWebService {
 	 * Retrieves the notification of the logged in user.
 	 * @response.representation.200.mediaType application/xml, application/json
 	 * @response.representation.200.doc The notifications
-   * @response.representation.200.example {@link org.olat.notifications.restapi.vo.Examples#SAMPLE_INFOVOes}
-   * @response.representation.404.doc The identity not found
-   * @param date The date (optional)
+	 * @response.representation.200.example {@link org.olat.notifications.restapi.vo.Examples#SAMPLE_INFOVOes}
+	 * @response.representation.404.doc The identity not found
+	 * @param date The date (optional)
+	 * @param type The type of notifications (User, Forum...) (optional)
 	 * @param httpRequest The HTTP request
 	 * @return an xml or json representation of a the user being search. The xml
 	 *         correspond to a <code>SubscriptionInfoVO</code>. <code>SubscriptionInfoVO</code>

src/main/java/org/olat/restapi/repository/course/CourseElementWebService.java

@@ -454,7 +454,7 @@ public class CourseElementWebService extends AbstractCourseNodeWebService {
 	}
 	
 	/**
-	 * This upudate a Folder Element onto a given course.
+	 * This updates a Folder Element onto a given course.
    * @response.representation.mediaType application/x-www-form-urlencoded
 	 * @response.representation.200.qname {http://www.example.com}courseNodeVO
    * @response.representation.200.mediaType application/xml, application/json

src/main/java/org/olat/user/restapi/ContactsWebService.java

@@ -53,6 +53,15 @@ import org.olat.group.BusinessGroupManagerImpl;
 @Path("contacts")
 public class ContactsWebService {
 	
+	/**
+	 * Retrieve the contacts of the logged in identity.
+	 * @response.representation.200.doc The list of contacts
+	 * @param start
+	 * @param limit
+	 * @param httpRequest The HTTP request
+	 * @param uriInfo The URI information
+	 * @return The list of contacts
+	 */
 	@GET
 	@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
 	public Response getMyContacts(@QueryParam("start") @DefaultValue("0") Integer start,