From 2e62362900f50762a2a7d808fa2791672621e182 Mon Sep 17 00:00:00 2001 From: f-w Date: Fri, 1 Sep 2023 11:51:16 -0700 Subject: [PATCH] use markdown-it-include pkg for re-usable content --- docs/.vuepress/config.js | 25 +++++++++----- docs/docs/api/administrator.md | 36 ++++++++++++++------- docs/docs/api/config.md | 18 ++++------- docs/docs/api/notification.md | 35 ++++++++++++++------ docs/docs/api/subscription.md | 35 +++++++++++++------- docs/docs/shared/filterQueryParam.md | 30 +++++++++++++++++ docs/docs/shared/filterQueryParamCode.md | 1 + docs/docs/shared/filterQueryParamExample.md | 12 +++++++ docs/docs/shared/whereQueryParam.md | 11 +++++++ docs/docs/shared/whereQueryParamCode.md | 1 + docs/docs/shared/whereQueryParamExample.md | 10 ++++++ docs/package.json | 1 + docs/yarn.lock | 5 +++ 13 files changed, 166 insertions(+), 54 deletions(-) create mode 100644 docs/docs/shared/filterQueryParam.md create mode 100644 docs/docs/shared/filterQueryParamCode.md create mode 100644 docs/docs/shared/filterQueryParamExample.md create mode 100644 docs/docs/shared/whereQueryParam.md create mode 100644 docs/docs/shared/whereQueryParamCode.md create mode 100644 docs/docs/shared/whereQueryParamExample.md diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index fee2d4c27..02ffc006f 100644 --- 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 index c589892de..018a16243 100644 --- 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 ``` @@ -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 index 6962c1112..c31de7188 100644 --- 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 index fdbe57f0d..8513c2dee 100644 --- 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 index f3e063290..15bd861e9 100644 --- a/docs/docs/api/subscription.md +++ b/docs/docs/api/subscription.md @@ -266,12 +266,11 @@ 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 @@ -279,6 +278,16 @@ GET /subscriptions - 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 ``` @@ -290,11 +299,7 @@ GET /subscriptions/count?where[property]=value - 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 new file mode 100644 index 000000000..cd03effa3 --- /dev/null +++ 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 new file mode 100644 index 000000000..06008dc4c --- /dev/null +++ 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 new file mode 100644 index 000000000..78bf111be --- /dev/null +++ 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 new file mode 100644 index 000000000..e488337a0 --- /dev/null +++ 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 new file mode 100644 index 000000000..2b747e403 --- /dev/null +++ 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 new file mode 100644 index 000000000..da1e1989e --- /dev/null +++ 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 index 58c4fb68e..f38ce8ebc 100644 --- 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 index 533ced3c0..15ab81b95 100644 --- 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"