add attachment API reference

src/server/models/openapi/v1-response.js

@@ -0,0 +1,16 @@
+/**
+ * @swagger
+ *
+ *  components:
+ *    schemas:
+ *      V1Response:
+ *        ok:
+ *          type: boolean
+ *          description: API is succeeded
+ *          example: true
+ *    responses:
+ *      403:
+ *        description: 'Forbidden'
+ *      500:
+ *        description: 'Internal Server Error'
+ */

src/server/routes/apiv3/users.js

@@ -21,6 +21,51 @@ const validator = {};
  *    name: Users
  */
 
+/**
+ * @swagger
+ *
+ *  components:
+ *    schemas:
+ *      User:
+ *        type: object
+ *        properties:
+ *          _id:
+ *            type: string
+ *            description: user ID
+ *            example: '0123456789abcdef01234567'
+ *          __v:
+ *            type: integer
+ *            description: DB record version
+ *            example: 0
+ *          lang:
+ *            type: string
+ *            description: language
+ *            example: 'en-US'
+ *          status:
+ *            type: integer
+ *            description: status
+ *            example: 0
+ *          admin:
+ *            type: boolean
+ *            description: whether the admin
+ *          email:
+ *            type: string
+ *            description: E-Mail address
+ *            example: 'alice@aaa.aaa'
+ *          username:
+ *            type: string
+ *            description: username
+ *            example: 'alice'
+ *          name:
+ *            type: string
+ *            description: full name
+ *            example: 'Alice'
+ *          createdAt:
+ *            type: string
+ *            description: date created at
+ *            example: '2010-01-01T00:00:00.000Z'
+ */
+
 module.exports = (crowi) => {
   const loginRequiredStrictly = require('../../middleware/login-required')(crowi);
   const adminRequired = require('../../middleware/admin-required')(crowi);

src/server/routes/attachment.js

@@ -7,6 +7,54 @@ const fs = require('fs');
 
 const ApiResponse = require('../util/apiResponse');
 
+/**
+ * @swagger
+ *  tags:
+ *    name: Attachments
+ */
+
+/**
+ * @swagger
+ *
+ *  components:
+ *    schemas:
+ *      Attachment:
+ *        type: object
+ *        properties:
+ *          _id:
+ *            type: string
+ *            description: attachment ID
+ *          __v:
+ *            type: integer
+ *            description: attachment version
+ *          fileFormat:
+ *            type: string
+ *            description: file format in MIME
+ *          fileName:
+ *            type: string
+ *            description: file name
+ *          originalName:
+ *            type: string
+ *            description: original file name
+ *          filePath:
+ *            type: string
+ *            description: file path
+ *          creator:
+ *            $ref: '#/components/schemas/User'
+ *          page:
+ *            type: string
+ *            description: page ID attached at
+ *          createdAt:
+ *            type: string
+ *            description: date created at
+ *          fileSize:
+ *            type: integer
+ *            description: file size
+ *          url:
+ *            type: string
+ *            description: attachment URL
+ */
+
 module.exports = function(crowi, app) {
   const Attachment = crowi.model('Attachment');
   const User = crowi.model('User');
@@ -185,6 +233,41 @@ module.exports = function(crowi, app) {
     return responseForAttachment(req, res, attachment);
   };
 
+  /**
+   * @swagger
+   *
+   *    /_api/attachments.list:
+   *      get:
+   *        tags: [Attachments]
+   *        description: Get list of attachments in page
+   *        requestBody:
+   *          required: true
+   *          content:
+   *            application/json:
+   *              schema:
+   *                properties:
+   *                  page_id:
+   *                    type: string
+   *                    description: page object ID
+   *        responses:
+   *          200:
+   *            description: Succeeded to get list of attachments.
+   *            content:
+   *              application/json:
+   *                schema:
+   *                  properties:
+   *                    ok:
+   *                      $ref: '#/components/schemas/V1Response/ok'
+   *                    attachments:
+   *                      type: array
+   *                      items:
+   *                        $ref: '#/components/schemas/Attachment'
+   *                      description: attachment list
+   *          403:
+   *            $ref: '#/components/responses/403'
+   *          500:
+   *            $ref: '#/components/responses/500'
+   */
   /**
    * @api {get} /attachments.list Get attachments of the page
    * @apiName ListAttachments
@@ -219,6 +302,50 @@ module.exports = function(crowi, app) {
     return res.json(ApiResponse.success(await fileUploader.checkLimit(fileSize)));
   };
 
+  /**
+   * @swagger
+   *
+   *    /_api/attachments.add:
+   *      post:
+   *        tags: [Attachments]
+   *        description: Add attachment to the page
+   *        requestBody:
+   *          required: true
+   *          content:
+   *            application/json:
+   *              schema:
+   *                properties:
+   *                  page_id:
+   *                    type: string
+   *                    description: page object ID
+   *                  file:
+   *                    type: string
+   *                    format: binary
+   *                    description: attachment data
+   *        responses:
+   *          200:
+   *            description: Succeeded to add attachment.
+   *            content:
+   *              application/json:
+   *                schema:
+   *                  properties:
+   *                    ok:
+   *                      $ref: '#/components/schemas/V1Response/ok'
+   *                    page:
+   *                      $ref: '#/components/schemas/Page'
+   *                    attachment:
+   *                      $ref: '#/components/schemas/Attachment'
+   *                    url:
+   *                      type: string
+   *                      description: attachment URL
+   *                    pageCreated:
+   *                      type: boolean
+   *                      description: whether the page was created
+   *          403:
+   *            $ref: '#/components/responses/403'
+   *          500:
+   *            $ref: '#/components/responses/500'
+   */
   /**
    * @api {post} /attachments.add Add attachment to the page
    * @apiName AddAttachments
@@ -320,6 +447,36 @@ module.exports = function(crowi, app) {
     return res.json(ApiResponse.success(result));
   };
 
+  /**
+   * @swagger
+   *
+   *    /_api/attachments.remove:
+   *      post:
+   *        tags: [Attachments]
+   *        description: Remove attachment
+   *        requestBody:
+   *          required: true
+   *          content:
+   *            application/json:
+   *              schema:
+   *                properties:
+   *                  attachment_id:
+   *                    type: string
+   *                    description: attachment ID
+   *        responses:
+   *          200:
+   *            description: Succeeded to remove attachment.
+   *            content:
+   *              application/json:
+   *                schema:
+   *                  properties:
+   *                    ok:
+   *                      $ref: '#/components/schemas/V1Response/ok'
+   *          403:
+   *            $ref: '#/components/responses/403'
+   *          500:
+   *            $ref: '#/components/responses/500'
+   */
   /**
    * @api {post} /attachments.remove Remove attachments
    * @apiName RemoveAttachments

src/server/routes/page.js

@@ -1,3 +1,73 @@
+/**
+ * @swagger
+ *
+ *  components:
+ *    schemas:
+ *      Page:
+ *        type: object
+ *        properties:
+ *          _id:
+ *            type: string
+ *            description: page ID
+ *          __v:
+ *            type: integer
+ *            description: DB record version
+ *          commentCount:
+ *            type: integer
+ *            description: count of comments
+ *          createdAt:
+ *            type: string
+ *            description: date created at
+ *          creator:
+ *            $ref: '#/components/schemas/User'
+ *          extended:
+ *            type: object
+ *            description: extend data
+ *          grant:
+ *            type: integer
+ *            description: grant
+ *          grantedUsers:
+ *            type: array
+ *            description: granted users
+ *            items:
+ *              type: string
+ *              description: user ID
+ *          lastUpdateUser:
+ *            $ref: '#/components/schemas/User'
+ *          liker:
+ *            type: array
+ *            description: granted users
+ *            items:
+ *              type: string
+ *              description: user ID
+ *          path:
+ *            type: string
+ *            description: page path
+ *          redirectTo:
+ *            type: string
+ *            description: redirect path
+ *          revision:
+ *            type: object
+ *            description: revision
+ *          seenUsers:
+ *            type: array
+ *            description: granted users
+ *            items:
+ *              type: string
+ *              description: user ID
+ *          status:
+ *            type: string
+ *            description: status
+ *            enum:
+ *              - 'wip'
+ *              - 'published'
+ *              - 'deleted'
+ *              - 'deprecated'
+ *          updatedAt:
+ *            type: string
+ *            description: date updated at
+ */
+
 /* eslint-disable no-use-before-define */
 module.exports = function(crowi, app) {
   const debug = require('debug')('growi:routes:page');