add API reference related to bookmark

src/server/models/openapi/paginate-result.js

@@ -45,4 +45,33 @@
  *          meta:
  *            type: number
  *            description: Object of pagination meta data (Default false).
+ *
+ */
+
+/**
+ * @swagger
+ *
+ *  components:
+ *    schemas:
+ *      V1PaginateResult:
+ *        type: object
+ *        properties:
+ *          meta:
+ *            type: object
+ *            properties:
+ *              total:
+ *                type: integer
+ *                description: Total number of documents in collection that match a query
+ *                example: 35
+ *              limit:
+ *                type: integer
+ *                description:
+ *                example: 10
+ *              offset:
+ *                type: integer
+ *                description: Only if specified or default page/offset values were used
+ *                example: 20
+ *          data:
+ *            type: object
+ *            description: Object of pagination meta data.
  */

src/server/routes/bookmark.js

@@ -1,3 +1,35 @@
+/**
+ * @swagger
+ *  tags:
+ *    name: Bookmarks
+ */
+
+/**
+ * @swagger
+ *
+ *  components:
+ *    schemas:
+ *      Bookmark:
+ *        type: object
+ *        properties:
+ *          _id:
+ *            type: string
+ *            description: page ID
+ *            example: 5e07345972560e001761fa63
+ *          __v:
+ *            type: integer
+ *            description: DB record version
+ *            example: 0
+ *          createdAt:
+ *            type: string
+ *            description: date created at
+ *            example: 2010-01-01T00:00:00.000Z
+ *          page:
+ *            $ref: '#/components/schemas/Page/properties/_id'
+ *          user:
+ *            $ref: '#/components/schemas/User/properties/_id'
+ */
+
 module.exports = function(crowi, app) {
   const debug = require('debug')('growi:routes:bookmark');
   const Bookmark = crowi.model('Bookmark');
@@ -7,6 +39,39 @@ module.exports = function(crowi, app) {
   const actions = {};
   actions.api = {};
 
+  /**
+   * @swagger
+   *
+   *    /_api/bookmarks.get:
+   *      get:
+   *        tags: [Bookmarks]
+   *        description: Get bookmark of the page with the user
+   *        requestBody:
+   *          required: true
+   *          content:
+   *            application/json:
+   *              schema:
+   *                properties:
+   *                  page_id:
+   *                    $ref: '#/components/schemas/Page/properties/_id'
+   *                required:
+   *                  - page_id
+   *        responses:
+   *          200:
+   *            description: Succeeded to get bookmark of the page with the user.
+   *            content:
+   *              application/json:
+   *                schema:
+   *                  properties:
+   *                    ok:
+   *                      $ref: '#/components/schemas/V1Response/ok'
+   *                    bookmark:
+   *                      $ref: '#/components/schemas/Bookmark'
+   *          403:
+   *            $ref: '#/components/responses/403'
+   *          500:
+   *            $ref: '#/components/responses/500'
+   */
   /**
    * @api {get} /bookmarks.get Get bookmark of the page with the user
    * @apiName GetBookmarks
@@ -30,8 +95,43 @@ module.exports = function(crowi, app) {
       });
   };
 
+
   /**
+   * @swagger
    *
+   *    /_api/bookmarks.list:
+   *      get:
+   *        tags: [Bookmarks]
+   *        description: Get bookmark list of the page with the user
+   *        requestBody:
+   *          required: true
+   *          content:
+   *            application/json:
+   *              schema:
+   *                properties:
+   *                  limit:
+   *                    $ref: '#/components/schemas/V1PaginateResult/properties/meta/properties/limit'
+   *                  offset:
+   *                    $ref: '#/components/schemas/V1PaginateResult/properties/meta/properties/offset'
+   *        responses:
+   *          200:
+   *            description: Succeeded to get bookmark of the page with the user.
+   *            content:
+   *              application/json:
+   *                schema:
+   *                  properties:
+   *                    ok:
+   *                      $ref: '#/components/schemas/V1Response/ok'
+   *                    meta:
+   *                      $ref: '#/components/schemas/V1PaginateResult/properties/meta'
+   *                    data:
+   *                      type: array
+   *                      items:
+   *                        $ref: '#/components/schemas/V1PaginateResult/properties/meta'
+   *          403:
+   *            $ref: '#/components/responses/403'
+   *          500:
+   *            $ref: '#/components/responses/500'
    */
   actions.api.list = function(req, res) {
     const paginateOptions = ApiPaginate.parseOptions(req.query);
@@ -46,6 +146,39 @@ module.exports = function(crowi, app) {
       });
   };
 
+  /**
+   * @swagger
+   *
+   *    /_api/bookmarks.add:
+   *      post:
+   *        tags: [Bookmarks]
+   *        description: Add bookmark of the page
+   *        requestBody:
+   *          required: true
+   *          content:
+   *            application/json:
+   *              schema:
+   *                properties:
+   *                  page_id:
+   *                    $ref: '#/components/schemas/Page/properties/_id'
+   *                required:
+   *                  - page_id
+   *        responses:
+   *          200:
+   *            description: Succeeded to add bookmark of the page.
+   *            content:
+   *              application/json:
+   *                schema:
+   *                  properties:
+   *                    ok:
+   *                      $ref: '#/components/schemas/V1Response/ok'
+   *                    bookmark:
+   *                      $ref: '#/components/schemas/Bookmark'
+   *          403:
+   *            $ref: '#/components/responses/403'
+   *          500:
+   *            $ref: '#/components/responses/500'
+   */
   /**
    * @api {post} /bookmarks.add Add bookmark of the page
    * @apiName AddBookmark
@@ -70,6 +203,37 @@ module.exports = function(crowi, app) {
     return res.json(ApiResponse.success(result));
   };
 
+  /**
+   * @swagger
+   *
+   *    /_api/bookmarks.remove:
+   *      post:
+   *        tags: [Bookmarks]
+   *        description: Remove bookmark of the page
+   *        requestBody:
+   *          required: true
+   *          content:
+   *            application/json:
+   *              schema:
+   *                properties:
+   *                  page_id:
+   *                    $ref: '#/components/schemas/Page/properties/_id'
+   *                required:
+   *                  - page_id
+   *        responses:
+   *          200:
+   *            description: Succeeded to remove bookmark of the page.
+   *            content:
+   *              application/json:
+   *                schema:
+   *                  properties:
+   *                    ok:
+   *                      $ref: '#/components/schemas/V1Response/ok'
+   *          403:
+   *            $ref: '#/components/responses/403'
+   *          500:
+   *            $ref: '#/components/responses/500'
+   */
   /**
    * @api {post} /bookmarks.remove Remove bookmark of the page
    * @apiName RemoveBookmark