add API reference related to comments.

src/server/routes/comment.js

@@ -1,4 +1,46 @@
-module.exports = function(crowi, app) {
+/**
+ * @swagger
+ *  tags:
+ *    name: Comments
+ */
+
+/**
+ * @swagger
+ *
+ *  components:
+ *    schemas:
+ *      Comment:
+ *        type: object
+ *        properties:
+ *          _id:
+ *            type: string
+ *            description: revision ID
+ *            example: 5e079a0a0afa6700170a75fb
+ *          __v:
+ *            type: integer
+ *            description: DB record version
+ *            example: 0
+ *          page:
+ *            $ref: '#/components/schemas/Page/properties/_id'
+ *          creator:
+ *            $ref: '#/components/schemas/User/properties/_id'
+ *          revision:
+ *            $ref: '#/components/schemas/Revision/properties/_id'
+ *          comment:
+ *            type: string
+ *            description: comment
+ *            example: good
+ *          commentPosition:
+ *            type: integer
+ *            description: comment position
+ *            example: 0
+ *          createdAt:
+ *            type: string
+ *            description: date created at
+ *            example: 2010-01-01T00:00:00.000Z
+ */
+
+ module.exports = function(crowi, app) {
   const logger = require('@alias/logger')('growi:routes:comment');
   const Comment = crowi.model('Comment');
   const User = crowi.model('User');
@@ -16,6 +58,41 @@ module.exports = function(crowi, app) {
   actions.api = api;
   api.validators = {};
 
+  /**
+   * @swagger
+   *
+   *    /_api/comments.get:
+   *      get:
+   *        tags: [Comments]
+   *        description: Get comments of the page of the revision
+   *        requestBody:
+   *          required: true
+   *          content:
+   *            application/json:
+   *              schema:
+   *                properties:
+   *                  page_id:
+   *                    $ref: '#/components/schemas/Page/properties/_id'
+   *                  revision_id:
+   *                    $ref: '#/components/schemas/Revision/properties/_id'
+   *        responses:
+   *          200:
+   *            description: Succeeded to get comments of the page of the revisiona.
+   *            content:
+   *              application/json:
+   *                schema:
+   *                  properties:
+   *                    ok:
+   *                      $ref: '#/components/schemas/V1Response/ok'
+   *                    comments:
+   *                      type: array
+   *                      items:
+   *                        $ref: '#/components/schemas/Comment'
+   *          403:
+   *            $ref: '#/components/responses/403'
+   *          500:
+   *            $ref: '#/components/responses/500'
+   */
   /**
    * @api {get} /comments.get Get comments of the page of the revision
    * @apiName GetComments
@@ -74,6 +151,48 @@ module.exports = function(crowi, app) {
     return validator;
   };
 
+  /**
+   * @swagger
+   *
+   *    /_api/comments.add:
+   *      post:
+   *        tags: [Comments]
+   *        description: Post comment for the page
+   *        requestBody:
+   *          required: true
+   *          content:
+   *            application/json:
+   *              schema:
+   *                properties:
+   *                  commentForm:
+   *                    type: object
+   *                    properties:
+   *                      page_id:
+   *                        $ref: '#/components/schemas/Page/properties/_id'
+   *                      revision_id:
+   *                        $ref: '#/components/schemas/Revision/properties/_id'
+   *                      comment:
+   *                        $ref: '#/components/schemas/Comment/properties/comment'
+   *                      comment_position:
+   *                        $ref: '#/components/schemas/Comment/properties/commentPosition'
+   *                required:
+   *                  - commentForm
+   *        responses:
+   *          200:
+   *            description: Succeeded to post comment for the page.
+   *            content:
+   *              application/json:
+   *                schema:
+   *                  properties:
+   *                    ok:
+   *                      $ref: '#/components/schemas/V1Response/ok'
+   *                    comment:
+   *                      $ref: '#/components/schemas/Comment'
+   *          403:
+   *            $ref: '#/components/responses/403'
+   *          500:
+   *            $ref: '#/components/responses/500'
+   */
   /**
    * @api {post} /comments.add Post comment for the page
    * @apiName PostComment
@@ -160,6 +279,51 @@ module.exports = function(crowi, app) {
     }
   };
 
+  /**
+   * @swagger
+   *
+   *    /_api/comments.update:
+   *      post:
+   *        tags: [Comments]
+   *        description: Update comment dody
+   *        requestBody:
+   *          required: true
+   *          content:
+   *            application/json:
+   *              schema:
+   *                properties:
+   *                  form:
+   *                    type: object
+   *                    properties:
+   *                      commentForm:
+   *                        type: object
+   *                        properties:
+   *                          page_id:
+   *                            $ref: '#/components/schemas/Page/properties/_id'
+   *                          revision_id:
+   *                            $ref: '#/components/schemas/Revision/properties/_id'
+   *                          comment:
+   *                            $ref: '#/components/schemas/Comment/properties/comment'
+   *                          comment_position:
+   *                            $ref: '#/components/schemas/Comment/properties/commentPosition'
+   *                required:
+   *                  - form
+   *        responses:
+   *          200:
+   *            description: Succeeded to update comment dody.
+   *            content:
+   *              application/json:
+   *                schema:
+   *                  properties:
+   *                    ok:
+   *                      $ref: '#/components/schemas/V1Response/ok'
+   *                    comment:
+   *                      $ref: '#/components/schemas/Comment'
+   *          403:
+   *            $ref: '#/components/responses/403'
+   *          500:
+   *            $ref: '#/components/responses/500'
+   */
   /**
    * @api {post} /comments.update Update comment dody
    * @apiName UpdateComment
@@ -206,6 +370,39 @@ module.exports = function(crowi, app) {
     // process notification if needed
   };
 
+  /**
+   * @swagger
+   *
+   *    /_api/comments.remove:
+   *      post:
+   *        tags: [Comments]
+   *        description: Remove specified comment
+   *        requestBody:
+   *          required: true
+   *          content:
+   *            application/json:
+   *              schema:
+   *                properties:
+   *                  comment_id:
+   *                    $ref: '#/components/schemas/Comment/properties/_id'
+   *                required:
+   *                  - comment_id
+   *        responses:
+   *          200:
+   *            description: Succeeded to remove specified comment.
+   *            content:
+   *              application/json:
+   *                schema:
+   *                  properties:
+   *                    ok:
+   *                      $ref: '#/components/schemas/V1Response/ok'
+   *                    comment:
+   *                      $ref: '#/components/schemas/Comment'
+   *          403:
+   *            $ref: '#/components/responses/403'
+   *          500:
+   *            $ref: '#/components/responses/500'
+   */
   /**
    * @api {post} /comments.remove Remove specified comment
    * @apiName RemoveComment