From af259ada01c20a66c2fefb37a384000a885c7762 Mon Sep 17 00:00:00 2001 From: Michael M Slusarz Date: Tue, 17 Dec 2024 19:00:22 -0700 Subject: [PATCH] doveadm: Rework response documentation The old 'fields' entry in data/doveadm.js has been replaced with the 'response' entry. This new entry allows for text description and data type output. Output example JSON server response in the HTTP API block. --- components/DoveadmComponent.vue | 14 ++++---- components/DoveadmHttpApiComponent.vue | 26 +++++++++++++++ data/doveadm.js | 33 ++++++++++++++----- lib/data/doveadm.data.js | 44 ++++++++++++++++---------- lib/doveadm.js | 6 ++++ 5 files changed, 93 insertions(+), 30 deletions(-) diff --git a/components/DoveadmComponent.vue b/components/DoveadmComponent.vue index 91a3e0a8b..50e55403a 100644 --- a/components/DoveadmComponent.vue +++ b/components/DoveadmComponent.vue @@ -49,7 +49,7 @@ function httpClick(k) { - +
@@ -80,20 +80,22 @@ function httpClick(k) { - - + +
Man Page
Return Values
Response Values - + + - + -
KeyValueTypeDescription
{{ elem.key }} + +
diff --git a/components/DoveadmHttpApiComponent.vue b/components/DoveadmHttpApiComponent.vue index 6a87b00e8..4feacb1c2 100644 --- a/components/DoveadmHttpApiComponent.vue +++ b/components/DoveadmHttpApiComponent.vue @@ -20,6 +20,22 @@ const jsonReq = "tag1" ] ] + +const resp = {} +if (d.response) { + for (let elem of d.response) { + resp[elem.key] = elem.example + } +} + +const jsonResp = +[ + [ + "doveadmResponse", + [ resp ], + "tag1" + ] +] diff --git a/data/doveadm.js b/data/doveadm.js index ec292223d..6cef96428 100644 --- a/data/doveadm.js +++ b/data/doveadm.js @@ -2,7 +2,8 @@ import { doveadm_arg_types, doveadm_args_query, doveadm_args_usermask, - doveadm_flag_types } from '../lib/doveadm.js' + doveadm_flag_types, + doveadm_response_types } from '../lib/doveadm.js' export const doveadm = { @@ -51,8 +52,21 @@ export const doveadm = { // deprecated: {}, // removed: {}, - // Fields/Values returned. Values are rendered w/Markdown. - // fields: {}, + // Response data. + // KEY = identifier + // response: { + // key: { + // // An example value to be used in documentation. + // example: 0, + // + // // The description of the response data type. + // // Rendered w/Markdown. + // text: `Description`, + // + // // The response data type + // type: doveadm_response_types.INTEGER, + // } + // }, // What doveadm flags does this command support (bit field) // Arguments are automatically added for each flag set @@ -237,8 +251,11 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only. text: `UID of user to apply operation to.`, }, }, - fields: { - 'entries': 0 + response: { + entries: { + type: doveadm_response_types.INTEGER, + text: `The number of cache entries flushed.` + }, }, man: 'doveadm-auth', text: `Flush authentication cache.`, @@ -1355,7 +1372,7 @@ to secure it. text: `Mailbox mask.` }, }, - fields: {}, + response: {}, flags: doveadm_flag_types.USER, plugin: 'mail-crypt', man: 'doveadm-mailbox-cryptokey', @@ -1375,7 +1392,7 @@ to secure it. text: `Mailbox mask.` }, }, - fields: {}, + response: {}, flags: doveadm_flag_types.USER, plugin: 'mail-crypt', man: 'doveadm-mailbox-cryptokey', @@ -1410,7 +1427,7 @@ to secure it. text: `Old password.` }, }, - fields: {}, + response: {}, flags: doveadm_flag_types.USER, plugin: 'mail-crypt', man: 'doveadm-mailbox-cryptokey', diff --git a/lib/data/doveadm.data.js b/lib/data/doveadm.data.js index 7816107be..d783c8b14 100644 --- a/lib/data/doveadm.data.js +++ b/lib/data/doveadm.data.js @@ -1,4 +1,4 @@ -import { doveadm_arg_types, doveadm_flag_types, getDoveadmCmdLine } from '../doveadm.js' +import { doveadm_arg_types, doveadm_flag_types, doveadm_response_types, getDoveadmCmdLine } from '../doveadm.js' import { getVitepressMd } from '../markdown.js' import { addWatchPaths, loadData, normalizeArrayData } from '../utility.js' import camelCase from 'camelcase' @@ -39,17 +39,26 @@ const doveadm_userfileargs = { function typeToString(type) { switch (type) { case doveadm_arg_types.ARRAY: - return 'array'; + return 'array' case doveadm_arg_types.BOOL: - return 'boolean'; + return 'boolean' case doveadm_arg_types.INTEGER: - return 'integer'; + return 'integer' case doveadm_arg_types.STRING: - return 'string'; + return 'string' case doveadm_arg_types.SEARCH_QUERY: - return 'search_query'; + return 'search_query' case doveadm_arg_types.ISTREAM: - return 'istream'; + return 'istream' + } +} + +function responseTypeLookup(type) { + switch (type) { + case doveadm_response_types.INTEGER: + return [ 'integer', 1 ] + case doveadm_response_types.STRING: + return [ 'string', 'example' ] } } @@ -97,19 +106,22 @@ async function normalizeDoveadm(doveadm) { } } - /* Return values. */ - if (v.fields) { - const fields = [] - for (const [k2, v2] of Object.entries(v.fields)) { - fields.push({ + /* Response values. */ + if (v.response) { + const response = [] + for (const [k2, v2] of Object.entries(v.response)) { + var rtl = responseTypeLookup(v2.type) + response.push({ + example: v2.example ?? rtl[1], key: k2, - value: v2 ? md.renderInline(String(v2)) : null + type: rtl[0], + text: v2.text ? md.renderInline(String(v2.text)) : null }) } - v.fields = fields + v.response = response } - if (!v.fields || !v.fields.length) { - delete v['fields'] + if (!v.response || !v.response.length) { + delete v['response'] } /* Text Description. */ diff --git a/lib/doveadm.js b/lib/doveadm.js index 548a9f057..b6367db44 100644 --- a/lib/doveadm.js +++ b/lib/doveadm.js @@ -16,6 +16,12 @@ export const doveadm_flag_types = { USERMASK: 4, } +/* List of Doveadm response value types. */ +export const doveadm_response_types = { + INTEGER: 1, + STRING: 2, +} + export const doveadm_args_query = { //example: ['mailbox', 'INBOX/myfoldertoo', 'savedbefore', 'since', '30d'], positional: true,