use markdown-it-include pkg for re-usable content

bcgov · Sep 2, 2023 · 8cd08a4 · 8cd08a4
1 parent 6cd6f1c
commit 8cd08a4
Show file tree

Hide file tree

Showing 13 changed files with 168 additions and 56 deletions.
diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
@@ -1,8 +1,9 @@
-import packageJson, {description} from '../../package';
-import {defineUserConfig, defaultTheme} from 'vuepress';
-import {getDirname, path} from '@vuepress/utils';
-import {docsearchPlugin} from '@vuepress/plugin-docsearch';
 import codeCopyPlugin from '@snippetors/vuepress-plugin-code-copy';
+import { docsearchPlugin } from '@vuepress/plugin-docsearch';
+import { getDirname, path } from '@vuepress/utils';
+import markdownItInclude from 'markdown-it-include';
+import { defaultTheme, defineUserConfig } from 'vuepress';
+import packageJson, { description } from '../../package';
 
 const __dirname = getDirname(import.meta.url);
 
@@ -24,10 +25,13 @@ export default defineUserConfig({
    * ref：https://v1.vuepress.vuejs.org/config/#head
    */
   head: [
-    ['meta', {name: 'theme-color', content: '#3eaf7c'}],
-    ['meta', {name: 'apple-mobile-web-app-capable', content: 'yes'}],
-    ['meta', {name: 'apple-mobile-web-app-status-bar-style', content: 'black'}],
-    ['link', {rel: 'icon', type: 'image/x-icon', href: `${base}favicon.ico`}],
+    ['meta', { name: 'theme-color', content: '#3eaf7c' }],
+    ['meta', { name: 'apple-mobile-web-app-capable', content: 'yes' }],
+    [
+      'meta',
+      { name: 'apple-mobile-web-app-status-bar-style', content: 'black' },
+    ],
+    ['link', { rel: 'icon', type: 'image/x-icon', href: `${base}favicon.ico` }],
     [
       'link',
       {
@@ -60,6 +64,11 @@ export default defineUserConfig({
     codeCopyPlugin(),
   ],
 
+  extendsMarkdown: (md) => {
+    // use more markdown-it plugins!
+    md.use(markdownItInclude);
+  },
+
   /**
    * Theme configuration, here is the default theme configuration for VuePress.
    *

diff --git a/docs/docs/api/administrator.md b/docs/docs/api/administrator.md
@@ -331,16 +331,25 @@ This API allows a super-admin or admin to search for administrators. An admin ca
   - super admin
   - admin
 - inputs
-  - a filter defining fields, where, include, order, offset, and limit. See [Loopback Querying Data](https://loopback.io/doc/en/lb4/Querying-data.html) for valid syntax and examples
-    - parameter name: filter
-    - required: false
-    - parameter type: query
-    - data type: object
+
+  - !!!include(./docs/shared/filterQueryParam.md)!!!
+
 - outcome
+
   - for super-admins, returns an array of _Administrators_ matching the filter
   - for admins, returns an array of one element - own record if the record matches the filter; empty array otherwise
   - forbidden otherwise
 
+- example
+
+  to retrieve administrators created in year 2023, run
+
+  ```sh
+  curl -X GET --header 'Accept: application/json' 'http://localhost:3000/api/administrators!!!include(./docs/shared/filterQueryParamCode.md)!!!'
+  ```
+
+  !!!include(./docs/shared/filterQueryParamExample.md)!!!
+
 ## Update Administrators
 
 ```
@@ -376,7 +385,7 @@ This API allows a super-admin or admin to update administrators. An admin can on
   - for super-admins or admin, successful count
   - forbidden otherwise
 
-## Count Administrators
+## Get Administrator Count
 
 ```
 GET /administrators/count
@@ -388,16 +397,19 @@ This API allows a super-admin or admin to count administrators by filter. An adm
   - super admin
   - admin
 - inputs
-
-  - a [where filter](https://loopback.io/doc/en/lb4/Where-filter.html)
-    - parameter name: where
-    - required: false
-    - parameter type: query
-    - data type: object
-
+  - !!!include(./docs/shared/whereQueryParam.md)!!!
 - outcome
   - for super-admins or admin, a count matching the filter
   - forbidden otherwise
+- example
+
+  to retrieve the count of administrators created in year 2023 , run
+
+  ```sh
+  curl -X GET --header 'Accept: application/json' 'http://localhost:3000/api/administrators/count!!!include(./docs/shared/whereQueryParamCode.md)!!!'
+  ```
+
+  !!!include(./docs/shared/whereQueryParamExample.md)!!!
 
 ## Delete an Administrator
 

diff --git a/docs/docs/api/config.md b/docs/docs/api/config.md
@@ -79,28 +79,22 @@ GET /configurations
   - super admin
   - admin
 - inputs
-  - a [filter](https://loopback.io/doc/en/lb4/Querying-data.html#filters) defining fields, where, include, order, offset, and limit
-    - parameter name: filter
-    - required: false
-    - parameter type: query
-    - data type: object
+
+  - !!!include(./docs/shared/filterQueryParam.md)!!!
+
 - outcome
 
   For admin request, a list of config items matching the filter; forbidden for user request
 
 - example
 
-  to retrieve config items with name _rsa_, run
+  to retrieve configs created in year 2023, run
 
   ```sh
-  curl -X GET --header 'Accept: application/json' 'http://localhost:3000/api/configurations?filter=%7B%22where%22%3A%20%7B%22name%22%3A%22rsa%22%7D%7D'
+  curl -X GET --header 'Accept: application/json' 'http://localhost:3000/api/configurations!!!include(./docs/shared/filterQueryParamCode.md)!!!'
   ```
 
-  the value of filter query parameter is the [stringified JSON](https://loopback.io/doc/en/lb4/Querying-data.html#using-stringified-json-in-rest-queries)
-
-  ```json
-  {"where": {"name": "rsa"}}
-  ```
+  !!!include(./docs/shared/filterQueryParamExample.md)!!!
 
 ## Create a Configuration
 

diff --git a/docs/docs/api/notification.md b/docs/docs/api/notification.md
@@ -359,12 +359,11 @@ GET /notifications
   - admin
   - authenticated user
 - inputs
-  - a filter defining fields, where, include, order, offset, and limit. See [Loopback Querying Data](https://loopback.io/doc/en/lb4/Querying-data.html#filters) for valid syntax and examples
-    - parameter name: filter
-    - required: false
-    - parameter type: query
-    - data type: object
+
+  - !!!include(./docs/shared/filterQueryParam.md)!!!
+
 - outcome
+
   - for admin requests, returns unabridged array of notification data matching the filter
   - for authenticated user requests, in addition to filter, following constraints are imposed on the returned array
     - only inApp notifications
@@ -375,6 +374,16 @@ GET /notifications
     - the internal field _readBy_ and _deletedBy_ are removed
   - forbidden to anonymous user requests
 
+- example
+
+  to retrieve notifications created in year 2023, run
+
+  ```sh
+  curl -X GET --header 'Accept: application/json' 'http://localhost:3000/api/notifications!!!include(./docs/shared/filterQueryParamCode.md)!!!'
+  ```
+
+  !!!include(./docs/shared/filterQueryParamExample.md)!!!
+
 ## Get Notification Count
 
 ```
@@ -386,11 +395,7 @@ GET /notifications/count
   - admin
   - authenticated user
 - inputs
-  - a [where filter](https://loopback.io/doc/en/lb4/Where-filter.html)
-    - parameter name: filter
-    - required: false
-    - parameter type: query
-    - data type: object
+  - !!!include(./docs/shared/whereQueryParam.md)!!!
 - outcome
 
   Validations rules are the same as _GET /notifications_. If passed, the output is a count of notifications matching the query
@@ -401,6 +406,16 @@ GET /notifications/count
   }
   ```
 
+- example
+
+  to retrieve the count of notifications created in year 2023, run
+
+  ```sh
+  curl -X GET --header 'Accept: application/json' 'http://localhost:3000/api/notifications/count!!!include(./docs/shared/whereQueryParamCode.md)!!!'
+  ```
+
+  !!!include(./docs/shared/whereQueryParamExample.md)!!!
+
 ## Create/Send Notifications
 
 ```

diff --git a/docs/docs/api/subscription.md b/docs/docs/api/subscription.md
@@ -266,35 +266,40 @@ GET /subscriptions
   - admin
   - authenticated user
 - inputs
-  - a filter defining fields, where, include, order, offset, and limit. See [Loopback Querying Data](https://loopback.io/doc/en/lb4/Querying-data.html) for valid syntax and examples
-    - parameter name: filter
-    - required: false
-    - parameter type: query
-    - data type: object
+
+  - !!!include(./docs/shared/filterQueryParam.md)!!!
+
 - outcome
+
   - for admin requests, returns unabridged array of subscription data matching the filter
   - for authenticated user requests, in addition to filter, following constraints are imposed on the returned array
     - only non-deleted subscriptions
     - only subscriptions created by the user
     - the _confirmationRequest_ field is removed.
   - forbidden for anonymous user requests
 
+- example
+
+  to retrieve subscriptions created in year 2023, run
+
+  ```sh
+  curl -X GET --header 'Accept: application/json' 'http://localhost:3000/api/subscriptions!!!include(./docs/shared/filterQueryParamCode.md)!!!'
+  ```
+
+  !!!include(./docs/shared/filterQueryParamExample.md)!!!
+
 ## Get Subscription Count
 
 ```
-GET /subscriptions/count?where[property]=value
+GET /subscriptions/count
 ```
 
 - permissions required, one of
   - super admin
   - admin
   - authenticated user
 - inputs
-  - a [where filter](https://loopback.io/doc/en/lb4/Where-filter.html)
-    - parameter name: where
-    - required: false
-    - parameter type: query
-    - data type: object
+  - !!!include(./docs/shared/whereQueryParam.md)!!!
 - outcome
 
   Validations rules are the same as _GET /subscriptions_. If passed, the output is a count of subscriptions matching the query
@@ -305,9 +310,15 @@ GET /subscriptions/count?where[property]=value
   }
   ```
 
-- examples
+- example
+
+  to retrieve the count of subscriptions created in year 2023, run
+
+  ```sh
+  curl -X GET --header 'Accept: application/json' 'http://localhost:3000/api/subscriptions/count!!!include(./docs/shared/whereQueryParamCode.md)!!!'
+  ```
 
-  See LoopBack [Get instance count](http://loopback.io/doc/en/lb3/PersistedModel-REST-API.html#get-instance-count) for examples.
+  !!!include(./docs/shared/whereQueryParamExample.md)!!!
 
 ## Create a Subscription
 

diff --git a/docs/docs/shared/filterQueryParam.md b/docs/docs/shared/filterQueryParam.md
@@ -0,0 +1,30 @@
+a filter containing properties _where_, _fields_, _order_, _skip_, and _limit_
+
+    - parameter name: filter
+    - required: false
+    - parameter type: query
+    - data type: object
+
+    The filter can be expressed as either
+
+      1. URL-encoded stringified JSON object (see example below); or
+      2. in the format supported by [qs](https://github.com/ljharb/qs), for example `?filter[where][created][$gte]="2023-01-01"&filter[where][created][$lt]="2024-01-01"`
+
+    Regardless, the filter will have to be parsed into a JSON object conforming to
+
+    ```json
+    {
+        "where": {...},
+        "fields": ...,
+        "order": ...,
+        "skip": ...,
+        "limit": ...,
+    }
+    ```
+
+    All properties are optional. The syntax for each property is documented, respectively
+    - for *where* , see MongoDB [Query Documents](https://www.mongodb.com/docs/manual/tutorial/query-documents/)
+    - for *fields* , see Mongoose [select](https://mongoosejs.com/docs/api/query.html#Query.prototype.select())
+    - for *order*, see Mongoose [sort](https://mongoosejs.com/docs/api/query.html#Query.prototype.sort())
+    - for *skip*, see MongoDB [cursor.skip](https://www.mongodb.com/docs/manual/reference/method/cursor.skip/)
+    - for *limit*, see MongoDB [cursor.limit](https://www.mongodb.com/docs/manual/reference/method/cursor.limit/)
diff --git a/docs/docs/shared/filterQueryParamCode.md b/docs/docs/shared/filterQueryParamCode.md
@@ -0,0 +1 @@
+?filter=%7B%22where%22%3A%7B%22created%22%3A%7B%22%24gte%22%3A%222023-01-01%22%2C%22%24lt%22%3A%222024-01-01%22%7D%7D%7D
diff --git a/docs/docs/shared/filterQueryParamExample.md b/docs/docs/shared/filterQueryParamExample.md
@@ -0,0 +1,12 @@
+the value of the filter query parameter is URL-encoded stringified JSON object
+
+    ```json
+    {
+      "where": {
+        "created": {
+          "$gte": "2023-01-01",
+          "$lt": "2024-01-01"
+        }
+      }
+    }
+    ```
diff --git a/docs/docs/shared/whereQueryParam.md b/docs/docs/shared/whereQueryParam.md
@@ -0,0 +1,11 @@
+a _where_ query parameter with value conforming to MongoDB [Query Documents](https://www.mongodb.com/docs/manual/tutorial/query-documents/)
+
+    - parameter name: where
+    - required: false
+    - parameter type: query
+    - data type: object
+
+    The value can be expressed as either
+
+      1. URL-encoded stringified JSON object (see example below); or
+      2. in the format supported by [qs](https://github.com/ljharb/qs), for example `?where[created][$gte]="2023-01-01"&where[created][$lt]="2024-01-01"`
diff --git a/docs/docs/shared/whereQueryParamCode.md b/docs/docs/shared/whereQueryParamCode.md
@@ -0,0 +1 @@
+?where=%7B%22created%22%3A%7B%22%24gte%22%3A%222023-01-01%22%2C%22%24lt%22%3A%222024-01-01%22%7D%7D
diff --git a/docs/docs/shared/whereQueryParamExample.md b/docs/docs/shared/whereQueryParamExample.md
@@ -0,0 +1,10 @@
+the value of the filter query parameter is URL-encoded stringified JSON object
+
+    ```json
+    {
+      "created": {
+        "$gte": "2023-01-01",
+        "$lt": "2024-01-01"
+      }
+    }
+    ```
diff --git a/docs/package.json b/docs/package.json
@@ -16,6 +16,7 @@
   "devDependencies": {
     "@snippetors/vuepress-plugin-code-copy": "^1.2.3",
     "@vuepress/plugin-docsearch": "^2.0.0-beta.66",
+    "markdown-it-include": "^2.0.0",
     "vuepress": "^2.0.0-beta.66"
   }
 }
diff --git a/docs/yarn.lock b/docs/yarn.lock
@@ -1306,6 +1306,11 @@ markdown-it-emoji@^2.0.2:
   resolved "https://registry.yarnpkg.com/markdown-it-emoji/-/markdown-it-emoji-2.0.2.tgz#cd42421c2fda1537d9cc12b9923f5c8aeb9029c8"
   integrity sha512-zLftSaNrKuYl0kR5zm4gxXjHaOI3FAOEaloKmRA5hijmJZvSjmxcokOLlzycb/HXlUFWzXqpIEoyEMCE4i9MvQ==
 
+markdown-it-include@^2.0.0:
+  version "2.0.0"
+  resolved "https://registry.yarnpkg.com/markdown-it-include/-/markdown-it-include-2.0.0.tgz#e86e3b3c68c8f0e0437e179ba919ffd28443127a"
+  integrity sha512-wfgIX92ZEYahYWiCk6Jx36XmHvAimeHN420csOWgfyZjpf171Y0xREqZWcm/Rwjzyd0RLYryY+cbNmrkYW2MDw==
+
 markdown-it@^13.0.1:
   version "13.0.1"
   resolved "https://registry.yarnpkg.com/markdown-it/-/markdown-it-13.0.1.tgz#c6ecc431cacf1a5da531423fc6a42807814af430"