Merge pull request #10023 from weseek/imprv/openapi-spec-properties-ref

imprv: OpenAPI spec properties ref

apps/app/src/server/models/openapi/object-id.ts

@@ -0,0 +1,10 @@
+/**
+ * @swagger
+ *
+ *  components:
+ *    schemas:
+ *      ObjectId:
+ *        type: string
+ *        description: Object ID
+ *        example: 5ae5fccfc5577b0004dbd8ab
+ */

apps/app/src/server/models/openapi/page.ts

@@ -3,14 +3,20 @@
  *
  *  components:
  *    schemas:
+ *      PagePath:
+ *        description: Page path
+ *        type: string
+ *        example: /path/to/page
+ *      PageGrant:
+ *        description: Grant for page
+ *        type: number
+ *        example: 1
  *      Page:
  *        description: Page
  *        type: object
  *        properties:
  *          _id:
- *            type: string
- *            description: page ID
- *            example: 5e07345972560e001761fa63
+ *            $ref: '#/components/schemas/ObjectId'
  *          __v:
  *            type: number
  *            description: DB record version
@@ -30,9 +36,7 @@
  *            description: extend data
  *            example: {}
  *          grant:
- *            type: number
- *            description: grant
- *            example: 1
+ *            $ref: '#/components/schemas/PageGrant'
  *          grantedUsers:
  *            type: array
  *            description: granted users
@@ -50,9 +54,7 @@
  *              description: user ID
  *            example: []
  *          path:
- *            type: string
- *            description: page path
- *            example: /
+ *            $ref: '#/components/schemas/PagePath'
  *          revision:
  *            type: string
  *            description: page revision

apps/app/src/server/models/openapi/paginate-result.js → apps/app/src/server/models/openapi/paginate-result.ts

@@ -4,6 +4,14 @@
  *
  *  components:
  *    schemas:
+ *      Offset:
+ *        description: Offset for pagination
+ *        type: integer
+ *        example: 0
+ *      Limit:
+ *        description: Limit for pagination
+ *        type: integer
+ *        example: 10
  *      PaginateResult:
  *        description: PaginateResult
  *        type: object
@@ -17,8 +25,7 @@
  *            type: number
  *            description: Total number of documents in collection that match a query
  *          limit:
- *            type: number
- *            description: Limit that was used
+ *            $ref: '#/components/schemas/Limit'
  *          hasPrevPage:
  *            type: number
  *            description: Availability of prev page.
@@ -32,8 +39,8 @@
  *            type: number
  *            description: Total number of pages.
  *          offset:
- *            type: number
  *            description: Only if specified or default page/offset values were used
+ *            $ref: '#/components/schemas/Offset'
  *          prefPage:
  *            type: number
  *            description: Previous page number if available or NULL
@@ -66,13 +73,10 @@
  *                description: Total number of documents in collection that match a query
  *                example: 35
  *              limit:
- *                type: integer
- *                description: Limit that was used
- *                example: 10
+ *                $ref: '#/components/schemas/Limit'
  *              offset:
- *                type: integer
  *                description: Only if specified or default page/offset values were used
- *                example: 20
+ *                $ref: '#/components/schemas/Offset'
  *          data:
  *            type: object
  *            description: Object of pagination meta data.

apps/app/src/server/models/openapi/revision.ts

@@ -3,27 +3,29 @@
  *
  *  components:
  *    schemas:
+ *      RevisionBody:
+ *        description: Revision content body
+ *        type: string
+ *        example: |
+ *          # Header
+ *
+ *          - foo
+ *          - bar
+ *
  *      Revision:
  *        description: Revision
  *        type: object
  *        properties:
  *          _id:
- *            type: string
- *            description: revision ID
- *            example: 5e0734e472560e001761fa68
+ *            $ref: '#/components/schemas/ObjectId'
  *          __v:
  *            type: number
  *            description: DB record version
  *            example: 0
  *          author:
- *            $ref: '#/components/schemas/User/properties/_id'
+ *            $ref: '#/components/schemas/ObjectId'
  *          body:
- *            type: string
- *            description: content body
- *            example: |
- *              # test
- *
- *              test
+ *            $ref: '#/components/schemas/RevisionBody'
  *          format:
  *            type: string
  *            description: format

apps/app/src/server/models/openapi/tag.ts

@@ -0,0 +1,32 @@
+/**
+ * @swagger
+ *
+ *  components:
+ *    schemas:
+ *      Tags:
+ *        description: Tags
+ *        type: array
+ *        items:
+ *          $ref: '#/components/schemas/TagName'
+ *        example: ['daily', 'report', 'tips']
+ *
+ *      TagName:
+ *        description: Tag name
+ *        type: string
+ *        example: daily
+ *
+ *      Tag:
+ *        description: Tag
+ *        type: object
+ *        properties:
+ *          _id:
+ *            type: string
+ *            description: tag ID
+ *            example: 5e2d6aede35da4004ef7e0b7
+ *          name:
+ *            $ref: '#/components/schemas/TagName'
+ *          count:
+ *            type: number
+ *            description: Count of tagged pages
+ *            example: 3
+ */

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

@@ -3,14 +3,15 @@
  *
  *  components:
  *    schemas:
+ *      V1ResponseOK:
+ *        description: API is succeeded
+ *        type: boolean
  *      V1Response:
  *        description: Response v1
  *        type: object
  *        properties:
  *          ok:
- *            type: boolean
- *            description: API is succeeded
- *            example: true
+ *            $ref: '#/components/schemas/V1ResponseOK'
  *    responses:
  *      403:
  *        description: 'Forbidden'

apps/app/src/server/routes/apiv3/bookmarks.js

@@ -42,7 +42,7 @@ const router = express.Router();
  *          page:
  *            $ref: '#/components/schemas/Page'
  *          user:
- *            $ref: '#/components/schemas/User/properties/_id'
+ *            $ref: '#/components/schemas/ObjectId'
  *      Bookmarks:
  *        description: User Root Bookmarks
  *        type: object

apps/app/src/server/routes/apiv3/page/index.ts

@@ -197,12 +197,12 @@ module.exports = (crowi) => {
    *            in: query
    *            description: page id
    *            schema:
-   *              $ref: '#/components/schemas/Page/properties/_id'
+   *              $ref: '#/components/schemas/ObjectId'
    *          - name: path
    *            in: query
    *            description: page path
    *            schema:
-   *              $ref: '#/components/schemas/Page/properties/path'
+   *              $ref: '#/components/schemas/PagePath'
    *        responses:
    *          200:
    *            description: Page data
@@ -313,9 +313,9 @@ module.exports = (crowi) => {
    *                    type: string
    *                    description: Text of page
    *                  path:
-   *                    $ref: '#/components/schemas/Page/properties/path'
+   *                    $ref: '#/components/schemas/PagePath'
    *                  grant:
-   *                    $ref: '#/components/schemas/Page/properties/grant'
+   *                    $ref: '#/components/schemas/PageGrant'
    *                  grantUserGroupIds:
    *                    type: string
    *                    description: UserGroup ID
@@ -363,13 +363,13 @@ module.exports = (crowi) => {
    *              schema:
    *                properties:
    *                  body:
-   *                    $ref: '#/components/schemas/Revision/properties/body'
+   *                    $ref: '#/components/schemas/RevisionBody'
    *                  pageId:
-   *                    $ref: '#/components/schemas/Page/properties/_id'
+   *                    $ref: '#/components/schemas/ObjectId'
    *                  revisionId:
-   *                    $ref: '#/components/schemas/Revision/properties/_id'
+   *                    $ref: '#/components/schemas/ObjectId'
    *                  grant:
-   *                    $ref: '#/components/schemas/Page/properties/grant'
+   *                    $ref: '#/components/schemas/PageGrant'
    *                  userRelatedGrantUserGroupIds:
    *                    type: array
    *                    items:
@@ -538,7 +538,7 @@ module.exports = (crowi) => {
    *            in: query
    *            description: page id
    *            schema:
-   *              $ref: '#/components/schemas/Page/properties/_id'
+   *              $ref: '#/components/schemas/ObjectId'
    *        responses:
    *          200:
    *            description: Successfully retrieved current grant data.
@@ -1011,7 +1011,7 @@ module.exports = (crowi) => {
    *              schema:
    *                properties:
    *                  pageId:
-   *                    $ref: '#/components/schemas/Page/properties/_id'
+   *                    $ref: '#/components/schemas/ObjectId'
    *        responses:
    *          200:
    *            description: Succeeded to update subscription status.

apps/app/src/server/routes/apiv3/pages/index.js

@@ -29,35 +29,6 @@ const router = express.Router();
 const LIMIT_FOR_LIST = 10;
 const LIMIT_FOR_MULTIPLE_PAGE_OP = 20;
 
-/**
- * @swagger
- *
- *  components:
- *    schemas:
- *      Tags:
- *        description: Tags
- *        type: array
- *        items:
- *          $ref: '#/components/schemas/Tag/properties/name'
- *        example: ['daily', 'report', 'tips']
- *
- *      Tag:
- *        description: Tag
- *        type: object
- *        properties:
- *          _id:
- *            type: string
- *            description: tag ID
- *            example: 5e2d6aede35da4004ef7e0b7
- *          name:
- *            type: string
- *            description: tag name
- *            example: daily
- *          count:
- *            type: number
- *            description: Count of tagged pages
- *            example: 3
- */
 /** @param {import('~/server/crowi').default} crowi Crowi instance */
 module.exports = (crowi) => {
   const loginRequired = require('../../../middlewares/login-required')(crowi, true);
@@ -234,9 +205,9 @@ module.exports = (crowi) => {
    *              schema:
    *                properties:
    *                  pageId:
-   *                    $ref: '#/components/schemas/Page/properties/_id'
+   *                    $ref: '#/components/schemas/ObjectId'
    *                  path:
-   *                    $ref: '#/components/schemas/Page/properties/path'
+   *                    $ref: '#/components/schemas/PagePath'
    *                  revisionId:
    *                    type: string
    *                    description: revision ID
@@ -360,7 +331,7 @@ module.exports = (crowi) => {
     *              schema:
     *                properties:
     *                  pageId:
-    *                    $ref: '#/components/schemas/Page/properties/_id'
+    *                    $ref: '#/components/schemas/ObjectId'
     *                required:
     *                  - pageId
     *        responses:
@@ -576,9 +547,9 @@ module.exports = (crowi) => {
    *              schema:
    *                properties:
    *                  pageId:
-   *                    $ref: '#/components/schemas/Page/properties/_id'
+   *                    $ref: '#/components/schemas/ObjectId'
    *                  pageNameInput:
-   *                    $ref: '#/components/schemas/Page/properties/path'
+   *                    $ref: '#/components/schemas/PagePath'
    *                  isRecursively:
    *                    type: boolean
    *                    description: whether duplicate page with descendants

apps/app/src/server/routes/attachment/api.js

@@ -110,7 +110,7 @@ const ApiResponse = require('../../util/apiResponse');
  *            description: original file name
  *            example: profile.png
  *          creator:
- *            $ref: '#/components/schemas/User/properties/_id'
+ *            $ref: '#/components/schemas/ObjectId'
  *          page:
  *            type: string
  *            description: page ID attached at
@@ -222,7 +222,7 @@ export const routesFactory = (crowi) => {
    *                schema:
    *                  properties:
    *                    ok:
-   *                      $ref: '#/components/schemas/V1Response/properties/ok'
+   *                      $ref: '#/components/schemas/V1ResponseOK'
    *                    attachment:
    *                      $ref: '#/components/schemas/AttachmentProfile'
    *          403:
@@ -289,7 +289,7 @@ export const routesFactory = (crowi) => {
    *              schema:
    *                properties:
    *                  attachment_id:
-   *                    $ref: '#/components/schemas/Attachment/properties/_id'
+   *                    $ref: '#/components/schemas/ObjectId'
    *                required:
    *                  - attachment_id
    *        responses:
@@ -300,7 +300,7 @@ export const routesFactory = (crowi) => {
    *                schema:
    *                  properties:
    *                    ok:
-   *                      $ref: '#/components/schemas/V1Response/properties/ok'
+   *                      $ref: '#/components/schemas/V1ResponseOK'
    *          403:
    *            $ref: '#/components/responses/403'
    *          500:
@@ -365,7 +365,7 @@ export const routesFactory = (crowi) => {
    *                schema:
    *                  properties:
    *                    ok:
-   *                      $ref: '#/components/schemas/V1Response/properties/ok'
+   *                      $ref: '#/components/schemas/V1ResponseOK'
    *          403:
    *            $ref: '#/components/responses/403'
    *          500:

apps/app/src/server/routes/comment.js

@@ -21,32 +21,34 @@ import { preNotifyService } from '../service/pre-notify';
  *
  *  components:
  *    schemas:
+ *      CommentBody:
+ *        description: The type for Comment.comment
+ *        type: string
+ *        example: good
+ *      CommentPosition:
+ *        description: comment position
+ *        type: number
+ *        example: 0
  *      Comment:
  *        description: Comment
  *        type: object
  *        properties:
  *          _id:
- *            type: string
- *            description: revision ID
- *            example: 5e079a0a0afa6700170a75fb
+ *            $ref: '#/components/schemas/ObjectId'
  *          __v:
  *            type: number
  *            description: DB record version
  *            example: 0
  *          page:
- *            $ref: '#/components/schemas/Page/properties/_id'
+ *            $ref: '#/components/schemas/ObjectId'
  *          creator:
- *            $ref: '#/components/schemas/User/properties/_id'
+ *            $ref: '#/components/schemas/ObjectId'
  *          revision:
- *            $ref: '#/components/schemas/Revision/properties/_id'
+ *            $ref: '#/components/schemas/ObjectId'
  *          comment:
- *            type: string
- *            description: comment
- *            example: good
+ *            $ref: '#/components/schemas/CommentBody'
  *          commentPosition:
- *            type: number
- *            description: comment position
- *            example: 0
+ *            $ref: '#/components/schemas/CommentPosition'
  *          createdAt:
  *            type: string
  *            description: date created at
@@ -88,11 +90,11 @@ module.exports = function(crowi, app) {
    *          - in: query
    *            name: page_id
    *            schema:
-   *              $ref: '#/components/schemas/Page/properties/_id'
+   *              $ref: '#/components/schemas/ObjectId'
    *          - in: query
    *            name: revision_id
    *            schema:
-   *              $ref: '#/components/schemas/Revision/properties/_id'
+   *              $ref: '#/components/schemas/ObjectId'
    *        responses:
    *          200:
    *            description: Succeeded to get comments of the page of the revision.
@@ -101,7 +103,7 @@ module.exports = function(crowi, app) {
    *                schema:
    *                  properties:
    *                    ok:
-   *                      $ref: '#/components/schemas/V1Response/properties/ok'
+   *                      $ref: '#/components/schemas/V1ResponseOK'
    *                    comments:
    *                      type: array
    *                      items:
@@ -190,13 +192,13 @@ module.exports = function(crowi, app) {
    *                    type: object
    *                    properties:
    *                      page_id:
-   *                        $ref: '#/components/schemas/Page/properties/_id'
+   *                        $ref: '#/components/schemas/ObjectId'
    *                      revision_id:
-   *                        $ref: '#/components/schemas/Revision/properties/_id'
+   *                        $ref: '#/components/schemas/ObjectId'
    *                      comment:
-   *                        $ref: '#/components/schemas/Comment/properties/comment'
+   *                        $ref: '#/components/schemas/CommentBody'
    *                      comment_position:
-   *                        $ref: '#/components/schemas/Comment/properties/commentPosition'
+   *                        $ref: '#/components/schemas/CommentPosition'
    *                required:
    *                  - commentForm
    *        responses:
@@ -207,7 +209,7 @@ module.exports = function(crowi, app) {
    *                schema:
    *                  properties:
    *                    ok:
-   *                      $ref: '#/components/schemas/V1Response/properties/ok'
+   *                      $ref: '#/components/schemas/V1ResponseOK'
    *                    comment:
    *                      $ref: '#/components/schemas/Comment'
    *          403:
@@ -336,13 +338,13 @@ module.exports = function(crowi, app) {
    *                        type: object
    *                        properties:
    *                          page_id:
-   *                            $ref: '#/components/schemas/Page/properties/_id'
+   *                            $ref: '#/components/schemas/ObjectId'
    *                          revision_id:
-   *                            $ref: '#/components/schemas/Revision/properties/_id'
+   *                            $ref: '#/components/schemas/ObjectId'
    *                          comment_id:
-   *                            $ref: '#/components/schemas/Comment/properties/_id'
+   *                            $ref: '#/components/schemas/ObjectId'
    *                          comment:
-   *                            $ref: '#/components/schemas/Comment/properties/comment'
+   *                            $ref: '#/components/schemas/CommentBody'
    *                required:
    *                  - form
    *        responses:
@@ -353,7 +355,7 @@ module.exports = function(crowi, app) {
    *                schema:
    *                  properties:
    *                    ok:
-   *                      $ref: '#/components/schemas/V1Response/properties/ok'
+   *                      $ref: '#/components/schemas/V1ResponseOK'
    *                    comment:
    *                      $ref: '#/components/schemas/Comment'
    *          403:
@@ -433,7 +435,7 @@ module.exports = function(crowi, app) {
    *              schema:
    *                properties:
    *                  comment_id:
-   *                    $ref: '#/components/schemas/Comment/properties/_id'
+   *                    $ref: '#/components/schemas/ObjectId'
    *                required:
    *                  - comment_id
    *        responses:
@@ -444,7 +446,7 @@ module.exports = function(crowi, app) {
    *                schema:
    *                  properties:
    *                    ok:
-   *                      $ref: '#/components/schemas/V1Response/properties/ok'
+   *                      $ref: '#/components/schemas/V1ResponseOK'
    *                    comment:
    *                      $ref: '#/components/schemas/Comment'
    *          403:

apps/app/src/server/routes/page.js

@@ -149,7 +149,7 @@ module.exports = function(crowi, app) {
    *          - in: query
    *            name: pageId
    *            schema:
-   *              $ref: '#/components/schemas/Page/properties/_id'
+   *              $ref: '#/components/schemas/ObjectId'
    *        responses:
    *          200:
    *            description: Succeeded to get page tags.
@@ -158,7 +158,7 @@ module.exports = function(crowi, app) {
    *                schema:
    *                  properties:
    *                    ok:
-   *                      $ref: '#/components/schemas/V1Response/properties/ok'
+   *                      $ref: '#/components/schemas/V1ResponseOK'
    *                    tags:
    *                      $ref: '#/components/schemas/Tags'
    *          403:
@@ -197,7 +197,7 @@ module.exports = function(crowi, app) {
    *          - in: query
    *            name: path
    *            schema:
-   *              $ref: '#/components/schemas/Page/properties/path'
+   *              $ref: '#/components/schemas/PagePath'
    *        responses:
    *          200:
    *            description: Succeeded to get UpdatePost setting list.
@@ -206,7 +206,7 @@ module.exports = function(crowi, app) {
    *                schema:
    *                  properties:
    *                    ok:
-   *                      $ref: '#/components/schemas/V1Response/properties/ok'
+   *                      $ref: '#/components/schemas/V1ResponseOK'
    *                    updatePost:
    *                      $ref: '#/components/schemas/UpdatePost'
    *          403:

apps/app/src/server/routes/search.ts

@@ -14,26 +14,28 @@ const logger = loggerFactory('growi:routes:search');
  *
  *   components:
  *     schemas:
+ *       ElasticsearchResultMeta:
+ *         type: object
+ *         properties:
+ *           took:
+ *             type: number
+ *             description: Time Elasticsearch took to execute a search(milliseconds)
+ *             example: 34
+ *           total:
+ *             type: number
+ *             description: Number of documents matching search criteria
+ *             example: 2
+ *           results:
+ *             type: number
+ *             description: Actual array length of search results
+ *             example: 2
+ *
  *       ElasticsearchResult:
  *         description: Elasticsearch result v1
  *         type: object
  *         properties:
  *           meta:
- *             type: object
- *             properties:
- *               took:
- *                 type: number
- *                 description: Time Elasticsearch took to execute a search(milliseconds)
- *                 example: 34
- *               total:
- *                 type: number
- *                 description: Number of documents matching search criteria
- *                 example: 2
- *               results:
- *                 type: number
- *                 description: Actual array length of search results
- *                 example: 2
- *
+ *             $ref: '#/components/schemas/ElasticsearchResultMeta'
  */
 module.exports = function(crowi: Crowi, app) {
   const ApiResponse = require('../util/apiResponse');
@@ -62,15 +64,15 @@ module.exports = function(crowi: Crowi, app) {
    *         - in: query
    *           name: path
    *           schema:
-   *             $ref: '#/components/schemas/Page/properties/path'
+   *             $ref: '#/components/schemas/PagePath'
    *         - in: query
    *           name: offset
    *           schema:
-   *             $ref: '#/components/schemas/V1PaginateResult/properties/meta/properties/offset'
+   *             $ref: '#/components/schemas/Offset'
    *         - in: query
    *           name: limit
    *           schema:
-   *             $ref: '#/components/schemas/V1PaginateResult/properties/meta/properties/limit'
+   *             $ref: '#/components/schemas/Limit'
    *       responses:
    *         200:
    *           description: Succeeded to get list of pages.
@@ -79,9 +81,9 @@ module.exports = function(crowi: Crowi, app) {
    *               schema:
    *                 properties:
    *                   ok:
-   *                     $ref: '#/components/schemas/V1Response/properties/ok'
+   *                     $ref: '#/components/schemas/V1ResponseOK'
    *                   meta:
-   *                     $ref: '#/components/schemas/ElasticsearchResult/properties/meta'
+   *                     $ref: '#/components/schemas/ElasticsearchResultMeta'
    *                   totalCount:
    *                     type: integer
    *                     description: total count of pages

apps/app/src/server/routes/tag.js

@@ -5,35 +5,6 @@ import PageTagRelation from '../models/page-tag-relation';
 import { Revision } from '../models/revision';
 import ApiResponse from '../util/apiResponse';
 
-/**
- * @swagger
- *
- *  components:
- *    schemas:
- *      Tags:
- *        description: Tags
- *        type: array
- *        items:
- *          $ref: '#/components/schemas/Tag/properties/name'
- *        example: ['daily', 'report', 'tips']
- *
- *      Tag:
- *        description: Tag
- *        type: object
- *        properties:
- *          _id:
- *            type: string
- *            description: tag ID
- *            example: 5e2d6aede35da4004ef7e0b7
- *          name:
- *            type: string
- *            description: tag name
- *            example: daily
- *          count:
- *            type: number
- *            description: Count of tagged pages
- *            example: 3
- */
 /** @param {import('~/server/crowi').default} crowi Crowi instance */
 module.exports = function(crowi, app) {
 
@@ -68,7 +39,7 @@ module.exports = function(crowi, app) {
    *                schema:
    *                  properties:
    *                    ok:
-   *                      $ref: '#/components/schemas/V1Response/properties/ok'
+   *                      $ref: '#/components/schemas/V1ResponseOK'
    *                    tags:
    *                      $ref: '#/components/schemas/Tags'
    *          403:
@@ -109,9 +80,9 @@ module.exports = function(crowi, app) {
    *              schema:
    *                properties:
    *                  pageId:
-   *                    $ref: '#/components/schemas/Page/properties/_id'
+   *                    $ref: '#/components/schemas/ObjectId'
    *                  revisionId:
-   *                    $ref: '#/components/schemas/Revision/properties/_id'
+   *                    $ref: '#/components/schemas/ObjectId'
    *                  tags:
    *                    $ref: '#/components/schemas/Tags'
    *        responses:
@@ -122,7 +93,7 @@ module.exports = function(crowi, app) {
    *                schema:
    *                  properties:
    *                    ok:
-   *                      $ref: '#/components/schemas/V1Response/properties/ok'
+   *                      $ref: '#/components/schemas/V1ResponseOK'
    *                    tags:
    *                      $ref: '#/components/schemas/Tags'
    *          403:
@@ -186,11 +157,11 @@ module.exports = function(crowi, app) {
    *          - in: query
    *            name: limit
    *            schema:
-   *              $ref: '#/components/schemas/V1PaginateResult/properties/meta/properties/limit'
+   *              $ref: '#/components/schemas/Limit'
    *          - in: query
    *            name: offset
    *            schema:
-   *              $ref: '#/components/schemas/V1PaginateResult/properties/meta/properties/offset'
+   *              $ref: '#/components/schemas/Offset'
    *        responses:
    *          200:
    *            description: Succeeded to tag list.
@@ -199,7 +170,7 @@ module.exports = function(crowi, app) {
    *                schema:
    *                  properties:
    *                    ok:
-   *                      $ref: '#/components/schemas/V1Response/properties/ok'
+   *                      $ref: '#/components/schemas/V1ResponseOK'
    *                    data:
    *                      type: array
    *                      items: