vmario/docs
1
0
Fork 0
mirror of https://github.com/sismics/docs.git synced 2024-11-22 05:57:57 +01:00
Code Issues Packages Projects Releases Wiki Activity

#103: API documentation for all resources except /document

Browse Source
This commit is contained in:
jendib 2016-05-12 01:26:02 +02:00
parent a13174ac4d
commit 177bbceaf4
No known key found for this signature in database
GPG Key ID: 06EE7F699579166F
11 changed files with 593 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
docs-web/src/main/java/com/sismics/docs/rest/resource/AclResource.java
View File

@ -31,7 +31,24 @@ import java.util.List;
public class AclResource extends BaseResource { public class AclResource extends BaseResource {
/** /**
* Add an ACL. * Add an ACL.
* *
* @api {put} /acl Add an ACL
* @apiName PutAcl
* @apiGroup Acl
* @apiParam {String} source Source ID
* @apiParam {String="READ","WRITE"} perm Permission
* @apiParam {String} target Target ID
* @apiParam {String="USER","GROUP","SHARE"} type Target type
* @apiSuccess {String} id Acl ID
* @apiSuccess {String} perm Permission
* @apiSuccess {String} name Target name
* @apiSuccess {String="USER","GROUP","SHARE"} type Target type
* @apiError (client) ForbiddenError Access denied
* @apiError (client) ValidationError Validation error
* @apiError (client) InvalidTarget This target does not exist
* @apiPermission user
* @apiVersion 1.5.0
*
* @param sourceId Source ID * @param sourceId Source ID
* @param permStr Permission * @param permStr Permission
* @param targetName Target name * @param targetName Target name
@ -110,6 +127,19 @@ public class AclResource extends BaseResource {
/** /**
* Deletes an ACL. * Deletes an ACL.
*
* @api {delete} /acl/:source/:perm/:target Delete an ACL
* @apiName DeleteAcl
* @apiGroup Acl
* @apiParam {String} source Source ID
* @apiParam {String="READ","WRITE"} perm Permission
* @apiParam {String} target Target ID
* @apiSuccess {String} status Status OK
* @apiError (client) ForbiddenError Access denied
* @apiError (client) ValidationError Validation error
* @apiError (client) AclError Cannot delete base ACL on a document or a tag
* @apiPermission user
* @apiVersion 1.5.0
* *
* @param sourceId Source ID * @param sourceId Source ID
* @param permStr Permission * @param permStr Permission
@ -162,6 +192,19 @@ public class AclResource extends BaseResource {
/** /**
* Search possible ACL target. * Search possible ACL target.
*
* @api {get} /acl/target/search Search in ACL targets
* @apiName GetAclTargetSearch
* @apiGroup Acl
* @apiParam {String} search Search query
* @apiSuccess {Object[]} users List of users
* @apiSuccess {String} users.name Username
* @apiSuccess {Object[]} groups List of groups
* @apiSuccess {String} groups.name Group name
* @apiError (client) ForbiddenError Access denied
* @apiError (client) ValidationError Validation error
* @apiPermission user
* @apiVersion 1.5.0
* *
* @param search Search query * @param search Search query
* @return Response * @return Response

82
docs-web/src/main/java/com/sismics/docs/rest/resource/AppResource.java
View File

@ -63,8 +63,19 @@ public class AppResource extends BaseResource {
private static final Logger log = LoggerFactory.getLogger(AppResource.class); private static final Logger log = LoggerFactory.getLogger(AppResource.class);
/** /**
* Return the information about the application. * Returns informations about the application.
* *
* @api {get} /app Get application informations
* @apiName GetApp
* @apiGroup App
* @apiSuccess {String} current_version API current version
* @apiSuccess {String} min_version API minimum version
* @apiSuccess {String} total_memory Allocated JVM memory (in bytes)
* @apiSuccess {String} free_memory Free JVM memory (in bytes)
* @apiError (client) ForbiddenError Access denied
* @apiPermission user
* @apiVersion 1.5.0
*
* @return Response * @return Response
*/ */
@GET @GET
@ -88,7 +99,26 @@ public class AppResource extends BaseResource {
/** /**
* Retrieve the application logs. * Retrieve the application logs.
* *
* @api {get} /app/log Get application logs
* @apiName GetAppLog
* @apiGroup App
* @apiParam {String="FATAL","ERROR","WARN","INFO","DEBUG"} level Minimum log level
* @apiParam {String} tag Filter on this logger tag
* @apiParam {String} message Filter on this message
* @apiParam {Number} limit Total number of logs to return
* @apiParam {Number} offset Start at this index
* @apiSuccess {String} total Total number of logs
* @apiSuccess {Object[]} logs List of logs
* @apiSuccess {String} logs.date Date
* @apiSuccess {String} logs.level Level
* @apiSuccess {String} logs.tag Tag
* @apiSuccess {String} logs.message Message
* @apiError (client) ForbiddenError Access denied
* @apiError (server) ServerError MEMORY appender not configured
* @apiPermission user
* @apiVersion 1.5.0
*
* @param minLevel Filter on logging level * @param minLevel Filter on logging level
* @param tag Filter on logger name / tag * @param tag Filter on logger name / tag
* @param message Filter on message * @param message Filter on message
@ -107,6 +137,7 @@ public class AppResource extends BaseResource {
if (!authenticate()) { if (!authenticate()) {
throw new ForbiddenClientException(); throw new ForbiddenClientException();
} }
// Get the memory appender // Get the memory appender
org.apache.log4j.Logger logger = org.apache.log4j.Logger.getRootLogger(); org.apache.log4j.Logger logger = org.apache.log4j.Logger.getRootLogger();
Appender appender = logger.getAppender("MEMORY"); Appender appender = logger.getAppender("MEMORY");
@ -141,7 +172,16 @@ public class AppResource extends BaseResource {
/** /**
* Destroy and rebuild Lucene index. * Destroy and rebuild Lucene index.
* *
* @api {post} /app/batch/reindex Rebuild the search index
* @apiName PostAppBatchReindex
* @apiGroup App
* @apiSuccess {String} status Status OK
* @apiError (client) ForbiddenError Access denied
* @apiError (server) IndexingError Error rebuilding the index
* @apiPermission admin
* @apiVersion 1.5.0
*
* @return Response * @return Response
*/ */
@POST @POST
@ -155,7 +195,7 @@ public class AppResource extends BaseResource {
try { try {
AppContext.getInstance().getIndexingService().rebuildIndex(); AppContext.getInstance().getIndexingService().rebuildIndex();
} catch (Exception e) { } catch (Exception e) {
throw new ServerException("IndexingError", "Error rebuilding index", e); throw new ServerException("IndexingError", "Error rebuilding the index", e);
} }
// Always return OK // Always return OK
@ -166,7 +206,16 @@ public class AppResource extends BaseResource {
/** /**
* Clean storage. * Clean storage.
* *
* @api {post} /app/batch/clean_storage Clean the file and DB storage
* @apiName PostAppBatchCleanStorage
* @apiGroup App
* @apiSuccess {String} status Status OK
* @apiError (client) ForbiddenError Access denied
* @apiError (server) FileError Error deleting orphan files
* @apiPermission admin
* @apiVersion 1.5.0
*
* @return Response * @return Response
*/ */
@POST @POST
@ -275,7 +324,16 @@ public class AppResource extends BaseResource {
/** /**
* Recompute the quota for each user. * Recompute the quota for each user.
* *
* @api {post} /app/batch/recompute_quote Recompute user quotas
* @apiName PostAppBatchRecomputeQuota
* @apiGroup App
* @apiSuccess {String} status Status OK
* @apiError (client) ForbiddenError Access denied
* @apiError (server) MissingFile File does not exist
* @apiPermission admin
* @apiVersion 1.5.0
*
* @return Response * @return Response
*/ */
@POST @POST
@ -327,6 +385,16 @@ public class AppResource extends BaseResource {
/** /**
* Add base ACLs to tags. * Add base ACLs to tags.
* *
* @api {post} /app/batch/recompute_quote Add base ACL to tags
* @apiDescription This resource must be used after migrating to 1.5.
* It will not do anything if base ACL are already present on tags.
* @apiName PostAppBatchTagAcls
* @apiGroup App
* @apiSuccess {String} status Status OK
* @apiError (client) ForbiddenError Access denied
* @apiPermission admin
* @apiVersion 1.5.0
*
* @return Response * @return Response
*/ */
@POST @POST

21
docs-web/src/main/java/com/sismics/docs/rest/resource/AuditLogResource.java
View File

@ -30,7 +30,26 @@ import javax.ws.rs.core.Response;
public class AuditLogResource extends BaseResource { public class AuditLogResource extends BaseResource {
/** /**
* Returns the list of all logs for a document or user. * Returns the list of all logs for a document or user.
* *
* @api {get} /auditlog Get audit logs
* @apiDescription If no document ID is provided, logs for the current user will be returned.
* @apiName GetAuditlog
* @apiGroup Auditlog
* @apiParam {String} [document] Document ID
* @apiSuccess {String} total Total number of logs
* @apiSuccess {Object[]} logs List of logs
* @apiSuccess {String} logs.id ID
* @apiSuccess {String} logs.username Username
* @apiSuccess {String} logs.target Entity ID
* @apiSuccess {String="Acl","Comment","Document","File","Group","Tag","User"} logs.class Entity type
* @apiSuccess {String="CREATE","UPDATE","DELETE"} logs.type Type
* @apiSuccess {String} logs.message Message
* @apiSuccess {Number} logs.create_date Create date (timestamp)
* @apiError (client) ForbiddenError Access denied
* @apiError (client) NotFound Document not found
* @apiPermission user
* @apiVersion 1.5.0
*
* @return Response * @return Response
*/ */
@GET @GET

45
docs-web/src/main/java/com/sismics/docs/rest/resource/CommentResource.java
View File

@ -25,6 +25,22 @@ import java.util.List;
public class CommentResource extends BaseResource { public class CommentResource extends BaseResource {
/** /**
* Add a comment. * Add a comment.
*
* @api {put} /comment Add a comment
* @apiName PutComment
* @apiGroup Comment
* @apiParam {String} id Document ID
* @apiParam {String} content Comment content
* @apiSuccess {String} id Comment ID
* @apiSuccess {String} content Content
* @apiSuccess {String} creator Username
* @apiSuccess {String} creator_gravatar Creator Gravatar hash
* @apiSuccess {Number} create_date Create date (timestamp)
* @apiError (client) ForbiddenError Access denied
* @apiError (client) ValidationError Validation error
* @apiError (client) NotFound Document not found
* @apiPermission user
* @apiVersion 1.5.0
* *
* @param documentId Document ID * @param documentId Document ID
* @param content Comment content * @param content Comment content
@ -67,7 +83,17 @@ public class CommentResource extends BaseResource {
/** /**
* Delete a comment. * Delete a comment.
* *
* @api {delete} /comment/:id Delete a comment
* @apiName DeleteComment
* @apiGroup Comment
* @apiParam {String} id Comment ID
* @apiSuccess {String} status Status OK
* @apiError (client) ForbiddenError Access denied
* @apiError (client) NotFound Comment or document not found
* @apiPermission user
* @apiVersion 1.5.0
*
* @param id Comment ID * @param id Comment ID
* @return Response * @return Response
*/ */
@ -105,7 +131,22 @@ public class CommentResource extends BaseResource {
/** /**
* Get all comments on a document. * Get all comments on a document.
* *
* @api {get} /comment/:id Get comments
* @apiName GetComment
* @apiGroup Comment
* @apiParam {String} id Document ID
* @apiParam {String} share Share ID
* @apiSuccess {Object[]} comments List of comments
* @apiSuccess {String} comments.id Comment ID
* @apiSuccess {String} comments.content Content
* @apiSuccess {String} comments.creator Username
* @apiSuccess {String} comments.creator_gravatar Creator Gravatar hash
* @apiSuccess {Number} comments.create_date Create date (timestamp)
* @apiError (client) NotFound Document not found
* @apiPermission none
* @apiVersion 1.5.0
*
* @param documentId DocumentID * @param documentId DocumentID
* @return Response * @return Response
*/ */

116
docs-web/src/main/java/com/sismics/docs/rest/resource/FileResource.java
View File

@ -61,7 +61,28 @@ import com.sismics.util.mime.MimeTypeUtil;
public class FileResource extends BaseResource { public class FileResource extends BaseResource {
/** /**
* Add a file (with or without a document). * Add a file (with or without a document).
* *
* @api {put} /file Add a file
* @apiDescription A file can be added without associated document, and will go in a temporary storage waiting for one.
* This resource accepts only multipart/form-data.
* @apiName PutFile
* @apiGroup File
* @apiParam {String} id Document ID
* @apiParam {String} file File data
* @apiSuccess {String} status Status OK
* @apiSuccess {String} id File ID
* @apiSuccess {Number} size File size (in bytes)
* @apiError (client) ForbiddenError Access denied
* @apiError (client) ValidationError Validation error
* @apiError (client) NotFound Document not found
* @apiError (server) StreamError Error reading the input file
* @apiError (server) ErrorGuessMime Error guessing mime type
* @apiError (client) InvalidFileType File type not recognized
* @apiError (client) QuotaReached Quota limit reached
* @apiError (server) FileError Error adding a file
* @apiPermission user
* @apiVersion 1.5.0
*
* @param documentId Document ID * @param documentId Document ID
* @param fileBodyPart File to add * @param fileBodyPart File to add
* @return Response * @return Response
@ -179,7 +200,20 @@ public class FileResource extends BaseResource {
/** /**
* Attach a file to a document. * Attach a file to a document.
* *
* @api {post} /file/:fileId Attach a file to a document
* @apiName PostFile
* @apiGroup File
* @apiParam {String} fileId File ID
* @apiParam {String} id Document ID
* @apiSuccess {String} status Status OK
* @apiError (client) ForbiddenError Access denied
* @apiError (client) ValidationError Validation error
* @apiError (client) IllegalFile File not orphan
* @apiError (server) AttachError Error attaching file to document
* @apiPermission user
* @apiVersion 1.5.0
*
* @param id File ID * @param id File ID
* @return Response * @return Response
*/ */
@ -235,7 +269,7 @@ public class FileResource extends BaseResource {
documentUpdatedAsyncEvent.setDocumentId(documentId); documentUpdatedAsyncEvent.setDocumentId(documentId);
AppContext.getInstance().getAsyncEventBus().post(documentUpdatedAsyncEvent); AppContext.getInstance().getAsyncEventBus().post(documentUpdatedAsyncEvent);
} catch (Exception e) { } catch (Exception e) {
throw new ClientException("AttachError", "Error attaching file to document", e); throw new ServerException("AttachError", "Error attaching file to document", e);
} }
// Always return OK // Always return OK
@ -246,7 +280,19 @@ public class FileResource extends BaseResource {
/** /**
* Reorder files. * Reorder files.
* *
* @api {post} /file/:reorder Reorder files
* @apiName PostFileReorder
* @apiGroup File
* @apiParam {String} id Document ID
* @apiParam {String[]} order List of files ID
* @apiSuccess {String} status Status OK
* @apiError (client) ForbiddenError Access denied
* @apiError (client) ValidationError Validation error
* @apiError (client) NotFound Document not found
* @apiPermission user
* @apiVersion 1.5.0
*
* @param documentId Document ID * @param documentId Document ID
* @param idList List of files ID in the new order * @param idList List of files ID in the new order
* @return Response * @return Response
@ -287,7 +333,24 @@ public class FileResource extends BaseResource {
/** /**
* Returns files linked to a document or not linked to any document. * Returns files linked to a document or not linked to any document.
* *
* @api {post} /file/list Get files
* @apiName GetFileList
* @apiGroup File
* @apiParam {String} id Document ID
* @apiParam {String} share Share ID
* @apiSuccess {Object[]} files List of files
* @apiSuccess {String} files.id ID
* @apiSuccess {String} files.mimetype MIME type
* @apiSuccess {String} files.document_id Document ID
* @apiSuccess {String} files.create_date Create date (timestamp)
* @apiSuccess {String} files.size File size (in bytes)
* @apiError (client) ForbiddenError Access denied
* @apiError (client) NotFound Document not found
* @apiError (server) FileError Unable to get the size of a file
* @apiPermission none
* @apiVersion 1.5.0
*
* @param documentId Document ID * @param documentId Document ID
* @param shareId Sharing ID * @param shareId Sharing ID
* @return Response * @return Response
@ -333,7 +396,18 @@ public class FileResource extends BaseResource {
/** /**
* Deletes a file. * Deletes a file.
* *
* @api {delete} /file/:id Delete a file
* @apiName DeleteFile
* @apiGroup File
* @apiParam {String} id File ID
* @apiParam {String} share Share ID
* @apiSuccess {String} status Status OK
* @apiError (client) ForbiddenError Access denied
* @apiError (client) NotFound File or document not found
* @apiPermission user
* @apiVersion 1.5.0
*
* @param id File ID * @param id File ID
* @return Response * @return Response
*/ */
@ -399,7 +473,21 @@ public class FileResource extends BaseResource {
/** /**
* Returns a file. * Returns a file.
* *
* @api {delete} /file/:id/data Get a file data
* @apiName GetFile
* @apiGroup File
* @apiParam {String} id File ID
* @apiParam {String} share Share ID
* @apiParam {String="web","thumb"} [size] Size variation
* @apiSuccess {Object} file The file data is the whole response
* @apiError (client) SizeError Size must be web or thumb
* @apiError (client) ForbiddenError Access denied or document not visible
* @apiError (client) NotFound File not found
* @apiError (server) ServiceUnavailable Error reading the file
* @apiPermission none
* @apiVersion 1.5.0
*
* @param fileId File ID * @param fileId File ID
* @return Response * @return Response
*/ */
@ -498,7 +586,18 @@ public class FileResource extends BaseResource {
/** /**
* Returns all files from a document, zipped. * Returns all files from a document, zipped.
* *
* @api {get} /file/zip Get zipped files
* @apiName GetFileZip
* @apiGroup File
* @apiParam {String} id Document ID
* @apiParam {String} share Share ID
* @apiSuccess {Object} file The ZIP file is the whole response
* @apiError (client) NotFound Document not found
* @apiError (server) InternalServerError Error creating the ZIP file
* @apiPermission none
* @apiVersion 1.5.0
*
* @param documentId Document ID * @param documentId Document ID
* @return Response * @return Response
*/ */
@ -542,7 +641,6 @@ public class FileResource extends BaseResource {
ByteStreams.copy(decryptedStream, zipOutputStream); ByteStreams.copy(decryptedStream, zipOutputStream);
zipOutputStream.closeEntry(); zipOutputStream.closeEntry();
} catch (Exception e) { } catch (Exception e) {
e.printStackTrace();
throw new WebApplicationException(e); throw new WebApplicationException(e);
} }
index++; index++;

99
docs-web/src/main/java/com/sismics/docs/rest/resource/GroupResource.java
View File

@ -34,7 +34,20 @@ import java.util.List;
public class GroupResource extends BaseResource { public class GroupResource extends BaseResource {
/** /**
* Add a group. * Add a group.
* *
* @api {put} /group Add a group
* @apiName PutGroup
* @apiGroup Group
* @apiParam {String} name Group name
* @apiParam {String} [parent] Parent group name
* @apiSuccess {String} status Status OK
* @apiError (client) ForbiddenError Access denied
* @apiError (client) ValidationError Validation error
* @apiError (client) GroupAlreadyExists This group already exists
* @apiError (client) ParentGroupNotFound Parent group not found
* @apiPermission admin
* @apiVersion 1.5.0
*
* @return Response * @return Response
*/ */
@PUT @PUT
@ -79,7 +92,21 @@ public class GroupResource extends BaseResource {
/** /**
* Update a group. * Update a group.
* *
* @api {post} /group/:name Update a group
* @apiName PostGroup
* @apiGroup Group
* @apiParam {String} name Group name
* @apiParam {String} [parent] Parent group name
* @apiSuccess {String} status Status OK
* @apiError (client) ForbiddenError Access denied
* @apiError (client) ValidationError Validation error
* @apiError (client) GroupAlreadyExists This group already exists
* @apiError (client) ParentGroupNotFound Parent group not found
* @apiError (client) NotFound Group not found
* @apiPermission admin
* @apiVersion 1.5.0
*
* @return Response * @return Response
*/ */
@POST @POST
@ -131,7 +158,17 @@ public class GroupResource extends BaseResource {
/** /**
* Delete a group. * Delete a group.
* *
* @api {delete} /group/:name Delete a group
* @apiName DeleteGroup
* @apiGroup Group
* @apiParam {String} name Group name
* @apiSuccess {String} status Status OK
* @apiError (client) ForbiddenError Access denied
* @apiError (client) NotFound Group not found
* @apiPermission admin
* @apiVersion 1.5.0
*
* @return Response * @return Response
*/ */
@DELETE @DELETE
@ -160,7 +197,19 @@ public class GroupResource extends BaseResource {
/** /**
* Add a user to a group. * Add a user to a group.
* *
* @api {put} /group/:name Add a user to a group
* @apiName PutGroupMember
* @apiGroup Group
* @apiParam {String} name Group name
* @apiParam {String} username Username
* @apiSuccess {String} status Status OK
* @apiError (client) ForbiddenError Access denied
* @apiError (client) ValidationError Validation error
* @apiError (client) NotFound Group or user not found
* @apiPermission admin
* @apiVersion 1.5.0
*
* @param groupName Group name * @param groupName Group name
* @param username Username * @param username Username
* @return Response * @return Response
@ -217,7 +266,19 @@ public class GroupResource extends BaseResource {
/** /**
* Remove an user from a group. * Remove an user from a group.
* *
* @api {delete} /group/:name/:username Remove a user from a group
* @apiName DeleteGroupMember
* @apiGroup Group
* @apiParam {String} name Group name
* @apiParam {String} username Username
* @apiSuccess {String} status Status OK
* @apiError (client) ForbiddenError Access denied
* @apiError (client) ValidationError Validation error
* @apiError (client) NotFound Group or user not found
* @apiPermission admin
* @apiVersion 1.5.0
*
* @param groupName Group name * @param groupName Group name
* @param username Username * @param username Username
* @return Response * @return Response
@ -260,7 +321,19 @@ public class GroupResource extends BaseResource {
/** /**
* Returns all active groups. * Returns all active groups.
* *
* @api {get} /group Get groups
* @apiName GetGroupList
* @apiGroup Group
* @apiParam {Number} sort_column Column index to sort on
* @apiParam {Boolean} asc If true, sort in ascending order
* @apiSuccess {Object[]} groups List of groups
* @apiSuccess {String} groups.name Name
* @apiSuccess {String} groups.parent Parent name
* @apiError (client) ForbiddenError Access denied
* @apiPermission user
* @apiVersion 1.5.0
*
* @param sortColumn Sort index * @param sortColumn Sort index
* @param asc If true, ascending sorting, else descending * @param asc If true, ascending sorting, else descending
* @return Response * @return Response
@ -291,7 +364,19 @@ public class GroupResource extends BaseResource {
/** /**
* Get a group. * Get a group.
* *
* @api {get} /group/:name Get a group
* @apiName GetGroup
* @apiGroup Group
* @apiParam {String} name Group name
* @apiSuccess {String} name Group name
* @apiSuccess {String} parent Parent name
* @apiSuccess {String[]} members List of members
* @apiError (client) ForbiddenError Access denied
* @apiError (client) NotFound Group not found
* @apiPermission user
* @apiVersion 1.5.0
*
* @param groupName Group name * @param groupName Group name
* @return Response * @return Response
*/ */

26
docs-web/src/main/java/com/sismics/docs/rest/resource/ShareResource.java
View File

@ -29,6 +29,21 @@ public class ShareResource extends BaseResource {
/** /**
* Add a share to a document. * Add a share to a document.
* *
* @api {put} /share Share a document
* @apiName PutShare
* @apiGroup Share
* @apiParam {String} id Document ID
* @apiParam {String} name Share name
* @apiSuccess {String} id Acl ID
* @apiSuccess {String="READ","WRITE"} perm Permission
* @apiSuccess {String} name Share name
* @apiSuccess {String="SHARE"} type ACL type (always SHARE)
* @apiError (client) ForbiddenError Access denied
* @apiError (client) ValidationError Validation error
* @apiError (client) NotFound Share not found
* @apiPermission user
* @apiVersion 1.5.0
*
* @param documentId Document ID * @param documentId Document ID
* @param name Share name * @param name Share name
* @return Response * @return Response
@ -76,6 +91,17 @@ public class ShareResource extends BaseResource {
/** /**
* Deletes a share. * Deletes a share.
* *
* @api {delete} /share/:id Unshare a document
* @apiName DeleteShare
* @apiGroup Share
* @apiParam {String} id Acl ID
* @apiSuccess {String} status Status OK
* @apiError (client) ForbiddenError Access denied
* @apiError (client) ShareNotFound Share not found
* @apiError (client) DocumentNotFound Document not found
* @apiPermission user
* @apiVersion 1.5.0
*
* @param id Share ID * @param id Share ID
* @return Response * @return Response
*/ */

77
docs-web/src/main/java/com/sismics/docs/rest/resource/TagResource.java
View File

@ -33,7 +33,19 @@ import java.util.Set;
public class TagResource extends BaseResource { public class TagResource extends BaseResource {
/** /**
* Returns the list of all visible tags. * Returns the list of all visible tags.
* *
* @api {get} /tag/list Get tags
* @apiName GetTagList
* @apiGroup Tag
* @apiSuccess {Object[]} tags List of tags
* @apiSuccess {String} tags.id ID
* @apiSuccess {String} tags.name Name
* @apiSuccess {String} tags.color Color
* @apiSuccess {String} tags.parent Parent
* @apiError (client) ForbiddenError Access denied
* @apiPermission user
* @apiVersion 1.5.0
*
* @return Response * @return Response
*/ */
@GET @GET
@ -73,6 +85,25 @@ public class TagResource extends BaseResource {
/** /**
* Returns a tag. * Returns a tag.
* *
* @api {get} /tag/:id Get a tag
* @apiName GetTag
* @apiGroup Tag
* @apiSuccess {String} id ID
* @apiSuccess {String} name Name
* @apiSuccess {String} creator Username of the creator
* @apiSuccess {String} color Color
* @apiSuccess {String} parent Parent
* @apiSuccess {Boolean} writable True if the tag is writable by the current user
* @apiSuccess {Object[]} acls List of ACL
* @apiSuccess {String} acls.id ID
* @apiSuccess {String="READ","WRITE"} acls.perm Permission
* @apiSuccess {String} acls.name Target name
* @apiSuccess {String="USER","GROUP","SHARE"} type Target type
* @apiError (client) ForbiddenError Access denied
* @apiError (client) NotFound Tag not found
* @apiPermission user
* @apiVersion 1.5.0
*
* @param id Tag ID * @param id Tag ID
* @return Response * @return Response
*/ */
@ -113,7 +144,21 @@ public class TagResource extends BaseResource {
/** /**
* Creates a new tag. * Creates a new tag.
* *
* @api {put} /tag Create a tag
* @apiName PutTag
* @apiGroup Tag
* @apiParam {String} name Name
* @apiParam {String} color Color
* @apiParam {String} parent Parent ID
* @apiSuccess {String} id Tag ID
* @apiError (client) ForbiddenError Access denied
* @apiError (client) ValidationError Validation error
* @apiError (client) SpacesNotAllowed Spaces are not allowed in tag name
* @apiError (client) ParentNotFound Parent not found
* @apiPermission user
* @apiVersion 1.5.0
*
* @param name Name * @param name Name
* @param color Color * @param color Color
* @param parentId Parent ID * @param parentId Parent ID
@ -178,7 +223,23 @@ public class TagResource extends BaseResource {
/** /**
* Update a tag. * Update a tag.
* *
* @api {post} /tag/:id Update a tag
* @apiName PostTag
* @apiGroup Tag
* @apiParam {String} id Tag ID
* @apiParam {String} name Name
* @apiParam {String} color Color
* @apiParam {String} parent Parent ID
* @apiSuccess {String} id Tag ID
* @apiError (client) ForbiddenError Access denied
* @apiError (client) ValidationError Validation error
* @apiError (client) SpacesNotAllowed Spaces are not allowed in tag name
* @apiError (client) ParentNotFound Parent not found
* @apiError (client) NotFound Tag not found
* @apiPermission user
* @apiVersion 1.5.0
*
* @param name Name * @param name Name
* @param color Color * @param color Color
* @param parentId Parent ID * @param parentId Parent ID
@ -240,6 +301,16 @@ public class TagResource extends BaseResource {
/** /**
* Delete a tag. * Delete a tag.
*
* @api {delete} /tag/:id Delete a tag
* @apiName DeleteTag
* @apiGroup Tag
* @apiParam {String} id Tag ID
* @apiSuccess {String} status Status OK
* @apiError (client) ForbiddenError Access denied
* @apiError (client) NotFound Tag not found
* @apiPermission user
* @apiVersion 1.5.0
* *
* @param id Tag ID * @param id Tag ID
* @return Response * @return Response

64
docs-web/src/main/java/com/sismics/docs/rest/resource/ThemeResource.java
View File

@ -39,7 +39,14 @@ import java.util.Map;
public class ThemeResource extends BaseResource { public class ThemeResource extends BaseResource {
/** /**
* Returns custom CSS stylesheet. * Returns custom CSS stylesheet.
* *
* @api {get} /theme/stylesheet Get the CSS stylesheet
* @apiName GetThemeStylesheet
* @apiGroup Theme
* @apiSuccess {String} stylesheet The whole response is the stylesheet
* @apiPermission none
* @apiVersion 1.5.0
*
* @return Response * @return Response
*/ */
@GET @GET
@ -60,6 +67,15 @@ public class ThemeResource extends BaseResource {
/** /**
* Returns the theme configuration. * Returns the theme configuration.
* *
* @api {get} /theme Get the theme configuration
* @apiName GetTheme
* @apiGroup Theme
* @apiSuccess {String} name Application name
* @apiSuccess {String} color Main color
* @apiSuccess {String} css Custom CSS
* @apiPermission none
* @apiVersion 1.5.0
*
* @return Response * @return Response
*/ */
@GET @GET
@ -75,6 +91,18 @@ public class ThemeResource extends BaseResource {
/** /**
* Change the theme configuration. * Change the theme configuration.
* *
* @api {post} /theme Change the theme configuration
* @apiName PostTheme
* @apiGroup Theme
* @apiParam {String} name Application name
* @apiParam {String} color Main color
* @apiParam {String} css Custom CSS
* @apiSuccess {String} status Status OK
* @apiError (client) ForbiddenError Access denied
* @apiError (client) ValidationError Validation error
* @apiPermission admin
* @apiVersion 1.5.0
*
* @param color Theme color * @param color Theme color
* @param name Application name * @param name Application name
* @param css Custom CSS * @param css Custom CSS
@ -117,6 +145,26 @@ public class ThemeResource extends BaseResource {
return Response.ok().entity(response.build()).build(); return Response.ok().entity(response.build()).build();
} }
/**
* Change a theme image.
*
* @api {put} /theme/image/:type Change a theme image
* @apiDescription This resource accepts only multipart/form-data.
* @apiName PutThemeImage
* @apiGroup Theme
* @apiParam {String="logo","background"} type Image type
* @apiParam {String} image Image data
* @apiSuccess {String} status Status OK
* @apiError (client) ForbiddenError Access denied
* @apiError (client) NoImageProvided An image is required
* @apiError (server) CopyError Error copying the image to the theme directory
* @apiPermission admin
* @apiVersion 1.5.0
*
* @param type Image type
* @param imageBodyPart Image data
* @return Response
*/
@PUT @PUT
@Path("image/{type: logo|background}") @Path("image/{type: logo|background}")
@Consumes("multipart/form-data") @Consumes("multipart/form-data")
@ -143,6 +191,20 @@ public class ThemeResource extends BaseResource {
return Response.ok().build(); return Response.ok().build();
} }
/**
* Get theme images.
*
* @api {get} /theme/image/:type Get a theme image
* @apiName GetThemeImage
* @apiGroup Theme
* @apiParam {String="logo","background"} type Image type
* @apiSuccess {String} image The whole response is the image
* @apiPermission none
* @apiVersion 1.5.0
*
* @param type Image type
* @return Response
*/
@GET @GET
@Produces("image/*") @Produces("image/*")
@Path("image/{type: logo|background}") @Path("image/{type: logo|background}")

55
docs-web/src/main/java/com/sismics/docs/rest/resource/UserResource.java
View File

@ -76,11 +76,13 @@ public class UserResource extends BaseResource {
* @apiParam {String{1..100}} email E-mail * @apiParam {String{1..100}} email E-mail
* @apiParam {Number} storage_quota Storage quota (in bytes) * @apiParam {Number} storage_quota Storage quota (in bytes)
* @apiSuccess {String} status Status OK * @apiSuccess {String} status Status OK
* @apiError (client) ForbiddenError Access denied
* @apiError (client) ValidationError Validation error
* @apiError (server) PrivateKeyError Error while generating a private key * @apiError (server) PrivateKeyError Error while generating a private key
* @apiError (client) AlreadyExistingUsername Login already used * @apiError (client) AlreadyExistingUsername Login already used
* @apiError (server) UnknownError Unknown server error * @apiError (server) UnknownError Unknown server error
* @apiPermission admin * @apiPermission admin
* @apiVersion 1.0.0 * @apiVersion 1.5.0
* *
* @param username User's username * @param username User's username
* @param password Password * @param password Password
@ -148,8 +150,10 @@ public class UserResource extends BaseResource {
* @apiParam {String{8..50}} password Password * @apiParam {String{8..50}} password Password
* @apiParam {String{1..100}} email E-mail * @apiParam {String{1..100}} email E-mail
* @apiSuccess {String} status Status OK * @apiSuccess {String} status Status OK
* @apiError (client) ForbiddenError Access denied
* @apiError (client) ValidationError Validation error
* @apiPermission user * @apiPermission user
* @apiVersion 1.0.0 * @apiVersion 1.5.0
* *
* @param password Password * @param password Password
* @param email E-Mail * @param email E-Mail
@ -198,9 +202,11 @@ public class UserResource extends BaseResource {
* @apiParam {String{1..100}} email E-mail * @apiParam {String{1..100}} email E-mail
* @apiParam {Number} storage_quota Storage quota (in bytes) * @apiParam {Number} storage_quota Storage quota (in bytes)
* @apiSuccess {String} status Status OK * @apiSuccess {String} status Status OK
* @apiError (client) ForbiddenError Access denied
* @apiError (client) ValidationError Validation error
* @apiError (client) UserNotFound User not found * @apiError (client) UserNotFound User not found
* @apiPermission admin * @apiPermission admin
* @apiVersion 1.0.0 * @apiVersion 1.5.0
* *
* @param username Username * @param username Username
* @param password Password * @param password Password
@ -262,7 +268,7 @@ public class UserResource extends BaseResource {
* @apiParam {String} username Username * @apiParam {String} username Username
* @apiSuccess {String} status Status OK or KO * @apiSuccess {String} status Status OK or KO
* @apiPermission none * @apiPermission none
* @apiVersion 1.0.0 * @apiVersion 1.5.0
* *
* @param username Username to check * @param username Username to check
* @return Response * @return Response
@ -299,9 +305,10 @@ public class UserResource extends BaseResource {
* @apiParam {String} code TOTP validation code * @apiParam {String} code TOTP validation code
* @apiParam {Boolean} remember If true, create a long lasted token * @apiParam {Boolean} remember If true, create a long lasted token
* @apiSuccess {String} auth_token A cookie named auth_token containing the token ID * @apiSuccess {String} auth_token A cookie named auth_token containing the token ID
* @apiError (client) ForbiddenError Access denied
* @apiError (client) ValidationCodeRequired A TOTP validation code is required * @apiError (client) ValidationCodeRequired A TOTP validation code is required
* @apiPermission none * @apiPermission none
* @apiVersion 1.0.0 * @apiVersion 1.5.0
* *
* @param username Username * @param username Username
* @param password Password * @param password Password
@ -373,9 +380,10 @@ public class UserResource extends BaseResource {
* @apiName PostUserLogout * @apiName PostUserLogout
* @apiGroup User * @apiGroup User
* @apiSuccess {String} auth_token An expired cookie named auth_token containing no value * @apiSuccess {String} auth_token An expired cookie named auth_token containing no value
* @apiError (client) ForbiddenError Access denied
* @apiError (server) AuthenticationTokenError Error deleting the authentication token * @apiError (server) AuthenticationTokenError Error deleting the authentication token
* @apiPermission user * @apiPermission user
* @apiVersion 1.0.0 * @apiVersion 1.5.0
* *
* @return Response * @return Response
*/ */
@ -421,9 +429,9 @@ public class UserResource extends BaseResource {
* @apiName DeleteUser * @apiName DeleteUser
* @apiGroup User * @apiGroup User
* @apiSuccess {String} status Status OK * @apiSuccess {String} status Status OK
* @apiError (client) ForbiddenError The admin user cannot be deleted * @apiError (client) ForbiddenError Access denied or the admin user cannot be deleted
* @apiPermission user * @apiPermission user
* @apiVersion 1.0.0 * @apiVersion 1.5.0
* *
* @return Response * @return Response
*/ */
@ -478,10 +486,10 @@ public class UserResource extends BaseResource {
* @apiName DeleteUserUsername * @apiName DeleteUserUsername
* @apiGroup User * @apiGroup User
* @apiSuccess {String} status Status OK * @apiSuccess {String} status Status OK
* @apiError (client) ForbiddenError Access denied or the admin user cannot be deleted
* @apiError (client) UserNotFound The user does not exist * @apiError (client) UserNotFound The user does not exist
* @apiError (client) ForbiddenError The admin user cannot be deleted
* @apiPermission admin * @apiPermission admin
* @apiVersion 1.0.0 * @apiVersion 1.5.0
* *
* @param username Username * @param username Username
* @return Response * @return Response
@ -555,7 +563,7 @@ public class UserResource extends BaseResource {
* @apiSuccess {String[]} base_functions Base functions * @apiSuccess {String[]} base_functions Base functions
* @apiSuccess {String[]} groups Groups * @apiSuccess {String[]} groups Groups
* @apiPermission none * @apiPermission none
* @apiVersion 1.0.0 * @apiVersion 1.5.0
* *
* @return Response * @return Response
*/ */
@ -624,9 +632,10 @@ public class UserResource extends BaseResource {
* @apiSuccess {Number} storage_quota Storage quota (in bytes) * @apiSuccess {Number} storage_quota Storage quota (in bytes)
* @apiSuccess {Number} storage_current Quota used (in bytes) * @apiSuccess {Number} storage_current Quota used (in bytes)
* @apiSuccess {String[]} groups Groups * @apiSuccess {String[]} groups Groups
* @apiError (client) ForbiddenError Access denied
* @apiError (client) UserNotFound The user does not exist * @apiError (client) UserNotFound The user does not exist
* @apiPermission user * @apiPermission user
* @apiVersion 1.0.0 * @apiVersion 1.5.0
* *
* @param username Username * @param username Username
* @return Response * @return Response
@ -671,15 +680,18 @@ public class UserResource extends BaseResource {
* @apiName GetUserList * @apiName GetUserList
* @apiGroup User * @apiGroup User
* @apiParam {Number} sort_column Column index to sort on * @apiParam {Number} sort_column Column index to sort on
* @apiSuccess {String[]} users List of users * @apiParam {Boolean} asc If true, sort in ascending order
* @apiParam {String} group Filter on this group
* @apiSuccess {Object[]} users List of users
* @apiSuccess {String} users.id ID * @apiSuccess {String} users.id ID
* @apiSuccess {String} users.username Username * @apiSuccess {String} users.username Username
* @apiSuccess {String} users.email E-mail * @apiSuccess {String} users.email E-mail
* @apiSuccess {Number} users.storage_quota Storage quota (in bytes) * @apiSuccess {Number} users.storage_quota Storage quota (in bytes)
* @apiSuccess {Number} users.storage_current Quota used (in bytes) * @apiSuccess {Number} users.storage_current Quota used (in bytes)
* @apiSuccess {Number} users.create_date Create date (timestamp) * @apiSuccess {Number} users.create_date Create date (timestamp)
* @apiError (client) ForbiddenError Access denied
* @apiPermission user * @apiPermission user
* @apiVersion 1.0.0 * @apiVersion 1.5.0
* *
* @param sortColumn Sort index * @param sortColumn Sort index
* @param asc If true, ascending sorting, else descending * @param asc If true, ascending sorting, else descending
@ -733,14 +745,15 @@ public class UserResource extends BaseResource {
* @apiDescription This resource lists all active token which can be used to log in to the current user account. * @apiDescription This resource lists all active token which can be used to log in to the current user account.
* @apiName GetUserSession * @apiName GetUserSession
* @apiGroup User * @apiGroup User
* @apiSuccess {String[]} sessions List of sessions * @apiSuccess {Object[]} sessions List of sessions
* @apiSuccess {Number} create_date Create date of this token * @apiSuccess {Number} create_date Create date of this token
* @apiSuccess {String} ip IP used to log in * @apiSuccess {String} ip IP used to log in
* @apiSuccess {String} user_agent User agent used to log in * @apiSuccess {String} user_agent User agent used to log in
* @apiSuccess {Number} last_connection_date Last connection date (timestamp) * @apiSuccess {Number} last_connection_date Last connection date (timestamp)
* @apiSuccess {Boolean} current If true, this token is the current one * @apiSuccess {Boolean} current If true, this token is the current one
* @apiError (client) ForbiddenError Access denied
* @apiPermission user * @apiPermission user
* @apiVersion 1.0.0 * @apiVersion 1.5.0
* *
* @return Response * @return Response
*/ */
@ -782,8 +795,9 @@ public class UserResource extends BaseResource {
* @apiName DeleteUserSession * @apiName DeleteUserSession
* @apiGroup User * @apiGroup User
* @apiSuccess {String} status Status OK * @apiSuccess {String} status Status OK
* @apiError (client) ForbiddenError Access denied
* @apiPermission user * @apiPermission user
* @apiVersion 1.0.0 * @apiVersion 1.5.0
* *
* @return Response * @return Response
*/ */
@ -816,8 +830,9 @@ public class UserResource extends BaseResource {
* @apiName PostUserEnableTotp * @apiName PostUserEnableTotp
* @apiGroup User * @apiGroup User
* @apiSuccess {String} secret Secret TOTP seed to initiate the algorithm * @apiSuccess {String} secret Secret TOTP seed to initiate the algorithm
* @apiError (client) ForbiddenError Access denied
* @apiPermission user * @apiPermission user
* @apiVersion 1.0.0 * @apiVersion 1.5.0
* *
* @return Response * @return Response
*/ */
@ -851,8 +866,10 @@ public class UserResource extends BaseResource {
* @apiGroup User * @apiGroup User
* @apiParam {String{1..100}} password Password * @apiParam {String{1..100}} password Password
* @apiSuccess {String} status Status OK * @apiSuccess {String} status Status OK
* @apiError (client) ForbiddenError Access denied
* @apiError (client) ValidationError Validation error
* @apiPermission user * @apiPermission user
* @apiVersion 1.0.0 * @apiVersion 1.5.0
* *
* @param password Password * @param password Password
* @return Response * @return Response

18
docs-web/src/main/java/com/sismics/docs/rest/resource/VocabularyResource.java
View File

@ -27,13 +27,14 @@ public class VocabularyResource extends BaseResource {
* @apiName GetVocabularyName * @apiName GetVocabularyName
* @apiGroup Vocabulary * @apiGroup Vocabulary
* @apiParam {String} name Vocabulary name * @apiParam {String} name Vocabulary name
* @apiSuccess {String[]} entries List of vocabulary entries * @apiSuccess {Object[]} entries List of vocabulary entries
* @apiSuccess {String} entries.id ID * @apiSuccess {String} entries.id ID
* @apiSuccess {String} entries.name Name * @apiSuccess {String} entries.name Name
* @apiSuccess {String} entries.value Value * @apiSuccess {String} entries.value Value
* @apiSuccess {Number} entries.order Order * @apiSuccess {Number} entries.order Order
* @apiError (client) ForbiddenError Access denied
* @apiPermission user * @apiPermission user
* @apiVersion 1.0.0 * @apiVersion 1.5.0
* *
* @param name Name * @param name Name
* @return Response * @return Response
@ -76,8 +77,10 @@ public class VocabularyResource extends BaseResource {
* @apiSuccess {String} name Name * @apiSuccess {String} name Name
* @apiSuccess {String} value Value * @apiSuccess {String} value Value
* @apiSuccess {Number} order Order * @apiSuccess {Number} order Order
* @apiError (client) ForbiddenError Access denied
* @apiError (client) ValidationError Validation error
* @apiPermission admin * @apiPermission admin
* @apiVersion 1.0.0 * @apiVersion 1.5.0
* *
* @param name Name * @param name Name
* @param value Value * @param value Value
@ -130,8 +133,11 @@ public class VocabularyResource extends BaseResource {
* @apiSuccess {String} name Name * @apiSuccess {String} name Name
* @apiSuccess {String} value Value * @apiSuccess {String} value Value
* @apiSuccess {Number} order Order * @apiSuccess {Number} order Order
* @apiError (client) ForbiddenError Access denied
* @apiError (client) ValidationError Validation error
* @apiError (client) NotFound Vocabulary not found
* @apiPermission admin * @apiPermission admin
* @apiVersion 1.0.0 * @apiVersion 1.5.0
* *
* @param id ID * @param id ID
* @param name Name * @param name Name
@ -197,8 +203,10 @@ public class VocabularyResource extends BaseResource {
* @apiGroup Vocabulary * @apiGroup Vocabulary
* @apiParam {String} id Entry ID * @apiParam {String} id Entry ID
* @apiSuccess {String} status Status OK * @apiSuccess {String} status Status OK
* @apiError (client) ForbiddenError Access denied
* @apiError (client) NotFound Vocabulary not found
* @apiPermission admin * @apiPermission admin
* @apiVersion 1.0.0 * @apiVersion 1.5.0
* *
* @param id ID * @param id ID
* @return Response * @return Response