add examples and revision schema

src/server/routes/apiv3/users.js

@@ -32,7 +32,7 @@ const validator = {};
  *          _id:
  *            type: string
  *            description: user ID
- *            example: '0123456789abcdef01234567'
+ *            example: 5ae5fccfc5577b0004dbd8ab
  *          __v:
  *            type: integer
  *            description: DB record version
@@ -48,22 +48,23 @@ const validator = {};
  *          admin:
  *            type: boolean
  *            description: whether the admin
+ *            example: false
  *          email:
  *            type: string
  *            description: E-Mail address
- *            example: 'alice@aaa.aaa'
+ *            example: alice@aaa.aaa
  *          username:
  *            type: string
  *            description: username
- *            example: 'alice'
+ *            example: alice
  *          name:
  *            type: string
  *            description: full name
- *            example: 'Alice'
+ *            example: Alice
  *          createdAt:
  *            type: string
  *            description: date created at
- *            example: '2010-01-01T00:00:00.000Z'
+ *            example: 2010-01-01T00:00:00.000Z
  */
 
 module.exports = (crowi) => {

src/server/routes/attachment.js

@@ -24,35 +24,45 @@ const ApiResponse = require('../util/apiResponse');
  *          _id:
  *            type: string
  *            description: attachment ID
+ *            example: 5e0734e072560e001761fa67
  *          __v:
  *            type: integer
  *            description: attachment version
+ *            example: 0
  *          fileFormat:
  *            type: string
  *            description: file format in MIME
+ *            example: image/png
  *          fileName:
  *            type: string
  *            description: file name
+ *            example: 601b7c59d43a042c0117e08dd37aad0aimage.png
  *          originalName:
  *            type: string
  *            description: original file name
+ *            example: image.png
  *          filePath:
  *            type: string
  *            description: file path
+ *            example: attachment/5e07345972560e001761fa63/6b0b3facf3628699263d760e18efd446.png
  *          creator:
  *            $ref: '#/components/schemas/User'
  *          page:
  *            type: string
  *            description: page ID attached at
+ *            example: 5e07345972560e001761fa63
  *          createdAt:
  *            type: string
  *            description: date created at
+ *            example: 2010-01-01T00:00:00.000Z
  *          fileSize:
  *            type: integer
  *            description: file size
+ *            example: 3494332
  *          url:
  *            type: string
  *            description: attachment URL
+ *            example: http://localhost/files/5e0734e072560e001761fa67
  */
 
 module.exports = function(crowi, app) {
@@ -247,8 +257,7 @@ module.exports = function(crowi, app) {
    *              schema:
    *                properties:
    *                  page_id:
-   *                    type: string
-   *                    description: page object ID
+   *                    $ref: '#/components/schemas/Page/properties/_id'
    *        responses:
    *          200:
    *            description: Succeeded to get list of attachments.
@@ -316,8 +325,7 @@ module.exports = function(crowi, app) {
    *              schema:
    *                properties:
    *                  page_id:
-   *                    type: string
-   *                    description: page object ID
+   *                    $ref: '#/components/schemas/Page/properties/_id'
    *                  file:
    *                    type: string
    *                    format: binary
@@ -336,8 +344,7 @@ module.exports = function(crowi, app) {
    *                    attachment:
    *                      $ref: '#/components/schemas/Attachment'
    *                    url:
-   *                      type: string
-   *                      description: attachment URL
+   *                      $ref: '#/components/schemas/Attachment/properties/url'
    *                    pageCreated:
    *                      type: boolean
    *                      description: whether the page was created
@@ -461,8 +468,7 @@ module.exports = function(crowi, app) {
    *              schema:
    *                properties:
    *                  attachment_id:
-   *                    type: string
-   *                    description: attachment ID
+   *                    $ref: '#/components/schemas/Attachment/properties/_id'
    *        responses:
    *          200:
    *            description: Succeeded to remove attachment.

src/server/routes/page.js

@@ -3,35 +3,76 @@
  *
  *  components:
  *    schemas:
+ *      Revision:
+ *        type: object
+ *        properties:
+ *          _id:
+ *            type: string
+ *            description: revision ID
+ *            example: 5e0734e472560e001761fa68
+ *          __v:
+ *            type: integer
+ *            description: DB record version
+ *            example: 0
+ *          author:
+ *            type: object
+ *            description: author
+ *            example: nil
+ *          body:
+ *            type: string
+ *            description: content body
+ *            example: |
+ *              \# test
+ *
+ *              test
+ *          createdAt:
+ *            type: string
+ *            description: date created at
+ *            example: 2010-01-01T00:00:00.000Z
+ *          format:
+ *            type: string
+ *            description: format
+ *            example: markdown
+ *          path:
+ *            type: string
+ *            description: path
+ *            example: /user/alice/test
  *      Page:
  *        type: object
  *        properties:
  *          _id:
  *            type: string
  *            description: page ID
+ *            example: 5e07345972560e001761fa63
  *          __v:
  *            type: integer
  *            description: DB record version
+ *            example: 0
  *          commentCount:
  *            type: integer
  *            description: count of comments
+ *            example: 3
  *          createdAt:
  *            type: string
  *            description: date created at
+ *            example: 2010-01-01T00:00:00.000Z
  *          creator:
  *            $ref: '#/components/schemas/User'
  *          extended:
  *            type: object
  *            description: extend data
+ *            example: {}
  *          grant:
  *            type: integer
  *            description: grant
+ *            example: 1
  *          grantedUsers:
  *            type: array
  *            description: granted users
  *            items:
  *              type: string
  *              description: user ID
+ *            example: ["5ae5fccfc5577b0004dbd8ab"]
  *          lastUpdateUser:
  *            $ref: '#/components/schemas/User'
  *          liker:
@@ -40,21 +81,24 @@
  *            items:
  *              type: string
  *              description: user ID
+ *            example: []
  *          path:
  *            type: string
  *            description: page path
+ *            example: /user/testdemocrowi/test
  *          redirectTo:
  *            type: string
  *            description: redirect path
+ *            example: /user/testdemocrowi/test2
  *          revision:
- *            type: object
- *            description: revision
+ *            $ref: '#/components/schemas/Revision'
  *          seenUsers:
  *            type: array
  *            description: granted users
  *            items:
  *              type: string
  *              description: user ID
+ *            example: 5ae5fccfc5577b0004dbd8ab
  *          status:
  *            type: string
  *            description: status
@@ -63,9 +107,11 @@
  *              - 'published'
  *              - 'deleted'
  *              - 'deprecated'
+ *            example: published
  *          updatedAt:
  *            type: string
  *            description: date updated at
+ *            example: 2010-01-01T00:00:00.000Z
  */
 
 /* eslint-disable no-use-before-define */