From ef18581e7178c7a3953d4d4966c9ee735e7c5b95 Mon Sep 17 00:00:00 2001 From: jendib Date: Fri, 13 May 2016 00:45:08 +0200 Subject: [PATCH] #103: API documentation for /document --- .../docs/rest/resource/DocumentResource.java | 160 +++++++++++++++++- .../docs/rest/resource/TagResource.java | 2 +- docs-web/src/main/webapp/package.json | 16 +- 3 files changed, 170 insertions(+), 8 deletions(-) diff --git a/docs-web/src/main/java/com/sismics/docs/rest/resource/DocumentResource.java b/docs-web/src/main/java/com/sismics/docs/rest/resource/DocumentResource.java index 1f7bccbc..918725fa 100644 --- a/docs-web/src/main/java/com/sismics/docs/rest/resource/DocumentResource.java +++ b/docs-web/src/main/java/com/sismics/docs/rest/resource/DocumentResource.java @@ -56,7 +56,56 @@ import java.util.*; public class DocumentResource extends BaseResource { /** * Returns a document. - * + * + * @api {get} /document/:id Get a document + * @apiName GetDocument + * @apiGroup Document + * @apiParam {String} id Document ID + * @apiParam {String} share Share ID + * @apiSuccess {String} id ID + * @apiSuccess {String} title Title + * @apiSuccess {String} description Description + * @apiSuccess {Number} create_date Create date (timestamp) + * @apiSuccess {String="eng","fra","jpn"} language Language + * @apiSuccess {Boolean} shared True if the document is shared + * @apiSuccess {Number} file_count Number of files in this document + * @apiSuccess {Object[]} tags List of tags + * @apiSuccess {String} tags.id ID + * @apiSuccess {String} tags.name Name + * @apiSuccess {String} tags.color Color + * @apiSuccess {String} subject Subject + * @apiSuccess {String} identifier Identifier + * @apiSuccess {String} publisher Publisher + * @apiSuccess {String} format Format + * @apiSuccess {String} source Source + * @apiSuccess {String} type Type + * @apiSuccess {String} coverage Coverage + * @apiSuccess {String} rights Rights + * @apiSuccess {String} creator Username of the creator + * @apiSuccess {Boolean} writable True if the document 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"} acls.type Target type + * @apiSuccess {Object[]} inherited_acls List of ACL not directly applied to this document + * @apiSuccess {String="READ","WRITE"} inherited_acls.perm Permission + * @apiSuccess {String} inherited_acls.source_id Source ID + * @apiSuccess {String} inherited_acls.source_name Source name + * @apiSuccess {String} inherited_acls.id ID + * @apiSuccess {String} inherited_acls.name Target name + * @apiSuccess {String="USER","GROUP","SHARE"} inherited_acls.type Target type + * @apiSuccess {Object[]} contributors List of users having contributed to this document + * @apiSuccess {String} contributors.username Username + * @apiSuccess {String} contributors.email E-mail + * @apiSuccess {Object[]} relations List of document related to this one + * @apiSuccess {String} relations.id ID + * @apiSuccess {String} relations.title Title + * @apiSuccess {String} relations.source True if this document is the source of the relation + * @apiError (client) NotFound Document not found + * @apiPermission none + * @apiVersion 1.5.0 + * * @param documentId Document ID * @param shareId Share ID * @return Response @@ -166,7 +215,22 @@ public class DocumentResource extends BaseResource { /** * Export a document to PDF. - * + * + * @api {get} /document/:id/pdf Export a document to PDF + * @apiName GetDocumentPdf + * @apiGroup Document + * @apiParam {String} id Document ID + * @apiParam {String} share Share ID + * @apiParam {Boolean} metadata If true, export metadata + * @apiParam {Boolean} comments If true, export comments + * @apiParam {Boolean} fitimagetopage If true, fit the images to pages + * @apiParam {Number} margin Margin around the pages, in millimeter + * @apiSuccess {String} pdf The whole response is the PDF file + * @apiError (client) NotFound Document not found + * @apiError (client) ValidationError Validation error + * @apiPermission none + * @apiVersion 1.5.0 + * * @param documentId Document ID * @param shareId Share ID * @param metadata Export metadata @@ -233,7 +297,33 @@ public class DocumentResource extends BaseResource { /** * Returns all documents. - * + * + * @api {get} /document/list Get documents + * @apiName GetDocumentList + * @apiGroup Document + * @apiParam {String} limit Total number of documents to return + * @apiParam {String} offset Start at this index + * @apiParam {Number} sort_column Column index to sort on + * @apiParam {Boolean} asc If true, sort in ascending order + * @apiParam {String} search Search query + * @apiSuccess {Number} total Total number of documents + * @apiSuccess {Object[]} documents List of documents + * @apiSuccess {String} documents.id ID + * @apiSuccess {String} documents.title Title + * @apiSuccess {String} documents.description Description + * @apiSuccess {Number} documents.create_date Create date (timestamp) + * @apiSuccess {String="eng","fra","jpn"} documents.language Language + * @apiSuccess {Boolean} documents.shared True if the document is shared + * @apiSuccess {Number} documents.file_count Number of files in this document + * @apiSuccess {Object[]} documents.tags List of tags + * @apiSuccess {String} documents.tags.id ID + * @apiSuccess {String} documents.tags.name Name + * @apiSuccess {String} documents.tags.color Color + * @apiError (client) ForbiddenError Access denied + * @apiError (server) SearchError Error searching in documents + * @apiPermission user + * @apiVersion 1.5.0 + * * @param limit Page limit * @param offset Page offset * @param sortColumn Sort column @@ -422,7 +512,30 @@ public class DocumentResource extends BaseResource { /** * Creates a new document. - * + * + * @api {put} /document Add a document + * @apiName PutDocument + * @apiGroup Document + * @apiParam {String} title Title + * @apiParam {String} [description] Description + * @apiParam {String} [subject] Subject + * @apiParam {String} [identifier] Identifier + * @apiParam {String} [publisher] Publisher + * @apiParam {String} [format] Format + * @apiParam {String} [source] Source + * @apiParam {String} [type] Type + * @apiParam {String} [coverage] Coverage + * @apiParam {String} [rights] Rights + * @apiParam {String[]} [tags] List of tags ID + * @apiParam {String[]} [relations] List of related documents ID + * @apiParam {String="eng","fra","jpn"} language Language + * @apiParam {Number} [create_date] Create date (timestamp) + * @apiSuccess {String} id Document ID + * @apiError (client) ForbiddenError Access denied + * @apiError (client) ValidationError Validation error + * @apiPermission user + * @apiVersion 1.5.0 + * * @param title Title * @param description Description * @param subject Subject @@ -532,7 +645,32 @@ public class DocumentResource extends BaseResource { /** * Updates the document. - * + * + * @api {post} /document/:id Update a document + * @apiName PostDocument + * @apiGroup Document + * @apiParam {String} id ID + * @apiParam {String} title Title + * @apiParam {String} [description] Description + * @apiParam {String} [subject] Subject + * @apiParam {String} [identifier] Identifier + * @apiParam {String} [publisher] Publisher + * @apiParam {String} [format] Format + * @apiParam {String} [source] Source + * @apiParam {String} [type] Type + * @apiParam {String} [coverage] Coverage + * @apiParam {String} [rights] Rights + * @apiParam {String[]} [tags] List of tags ID + * @apiParam {String[]} [relations] List of related documents ID + * @apiParam {String="eng","fra","jpn"} language Language + * @apiParam {Number} [create_date] Create date (timestamp) + * @apiSuccess {String} id Document ID + * @apiError (client) ForbiddenError Access denied or document not writable + * @apiError (client) ValidationError Validation error + * @apiError (client) NotFound Document not found + * @apiPermission user + * @apiVersion 1.5.0 + * * @param title Title * @param description Description * @return Response @@ -675,7 +813,17 @@ public class DocumentResource extends BaseResource { /** * Deletes a document. - * + * + * @api {delete} /document/:id Delete a document + * @apiName DeleteDocument + * @apiGroup Document + * @apiParam {String} id ID + * @apiSuccess {String} status Status OK + * @apiError (client) ForbiddenError Access denied + * @apiError (client) NotFound Document not found + * @apiPermission user + * @apiVersion 1.5.0 + * * @param id Document ID * @return Response */ diff --git a/docs-web/src/main/java/com/sismics/docs/rest/resource/TagResource.java b/docs-web/src/main/java/com/sismics/docs/rest/resource/TagResource.java index a8a0095a..452c2268 100644 --- a/docs-web/src/main/java/com/sismics/docs/rest/resource/TagResource.java +++ b/docs-web/src/main/java/com/sismics/docs/rest/resource/TagResource.java @@ -98,7 +98,7 @@ public class TagResource extends BaseResource { * @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 + * @apiSuccess {String="USER","GROUP","SHARE"} acls.type Target type * @apiError (client) ForbiddenError Access denied * @apiError (client) NotFound Tag not found * @apiPermission user diff --git a/docs-web/src/main/webapp/package.json b/docs-web/src/main/webapp/package.json index 7bf35d4f..97c22aee 100644 --- a/docs-web/src/main/webapp/package.json +++ b/docs-web/src/main/webapp/package.json @@ -14,7 +14,21 @@ "template": { "withCompare": false, "withGenerator": false - } + }, + "order": [ + "User", + "Group", + "Document", + "File", + "Tag", + "Comment", + "Share", + "Acl", + "Auditlog", + "App", + "Theme", + "Vocabulary" + ] }, "devDependencies": { "grunt": "^1.0.1",