From 5801e7071a0004dd8b4435c150b7d27c47a4457a Mon Sep 17 00:00:00 2001 From: Richard Willis Date: Thu, 6 Aug 2020 08:22:17 +0100 Subject: [PATCH] Add summaries & update version to 0.47 --- api/mailinabox.yml | 158 +++++++++++++++++++++++++++++---------------- 1 file changed, 102 insertions(+), 56 deletions(-) diff --git a/api/mailinabox.yml b/api/mailinabox.yml index 44b01cfd..c244d673 100644 --- a/api/mailinabox.yml +++ b/api/mailinabox.yml @@ -9,7 +9,7 @@ info: license: name: CC0 1.0 Universal url: https://creativecommons.org/publicdomain/zero/1.0/legalcode - version: '0.46.0' + version: 0.47.0 externalDocs: description: Find out more about Mail-in-a-box. url: https://mailinabox.email/ @@ -46,8 +46,9 @@ paths: get: tags: - User + summary: Get user information description: | - Get user information, used for user authentication. + Returns user information. Used for user authentication. Authenticate a user by supplying the auth token as a base64 encoded string in format `email:password` using basic authentication headers. @@ -78,8 +79,9 @@ paths: post: tags: - System + summary: Get system status description: | - Retrieve system status. Returns an array of statuses which can include headings. + Returns an array of statuses which can include headings. operationId: getSystemStatus responses: 200: @@ -107,7 +109,8 @@ paths: get: tags: - System - description: Retrieve installed Mail-in-a-Box version. + summary: Get system version + description: Returns installed Mail-in-a-Box version. operationId: getSystemVersion responses: 200: @@ -126,7 +129,8 @@ paths: post: tags: - System - description: Retrieve Mail-in-a-Box upstream version. + summary: Get system upstream version + description: Returns Mail-in-a-Box upstream version. operationId: getSystemUpstreamVersion responses: 200: @@ -145,7 +149,8 @@ paths: get: tags: - System - description: Retrieve system updates. + summary: Get system updates + description: Returns system (apt) updates. operationId: getSystemUpdates responses: 200: @@ -164,7 +169,8 @@ paths: post: tags: - System - description: Update system packages. + summary: Update system packages + description: Updates system (apt) packages. operationId: updateSystemPackages responses: 200: @@ -183,8 +189,9 @@ paths: get: tags: - System + summary: Get system privacy status description: | - Retrieve new-version check status. + Returns system privacy (new-version check) status. Response: @@ -207,8 +214,9 @@ paths: post: tags: - System + summary: Update system privacy description: | - Update new-version check status. + Updates system privacy (new-version) check status. Request: @@ -244,8 +252,9 @@ paths: get: tags: - System + summary: Get system reboot status description: | - Retrieve reboot status. + Returns the system reboot status. Response: @@ -268,7 +277,8 @@ paths: post: tags: - System - description: Reboot system. + summary: Reboot system + description: Reboots the system. operationId: rebootSystem responses: 200: @@ -287,8 +297,9 @@ paths: get: tags: - System + summary: Get system backup status description: | - Retrieve backup status. + Returns the system backup status. If the list of backups is empty, this implies no backups have been made yet. operationId: getSystemBackupStatus @@ -309,7 +320,8 @@ paths: get: tags: - System - description: Retrieve backup config. + summary: Get system backup config + description: Returns the system backup config. operationId: getSystemBackupConfig responses: 200: @@ -327,7 +339,8 @@ paths: post: tags: - System - description: Update backup config. + summary: Update system backup config + description: Updates the system backup config. operationId: updateSystemBackupConfig requestBody: required: true @@ -387,7 +400,8 @@ paths: get: tags: - SSL - description: Retrieve SSL status for all domains. + summary: Get SSL status + description: Returns the SSL status for all domains. operationId: getSSLStatus responses: 200: @@ -406,8 +420,9 @@ paths: post: tags: - SSL + summary: Generate SSL CSR description: | - Generate a Certificate Signing Request (CSR) for a domain & country code. + Generates a Certificate Signing Request (CSR) for a domain & country code. operationId: generateSSLCSR parameters: - in: path @@ -445,8 +460,9 @@ paths: post: tags: - SSL + summary: Install SSL certificate description: | - Install a custom certificate. The chain certificate is optional. + Installs a custom certificate. The chain certificate is optional. operationId: installSSLCertificate requestBody: required: true @@ -477,8 +493,9 @@ paths: post: tags: - SSL + summary: Provision SSL certificates description: | - Provision certificates for all domains. + Provisions certificates for all domains. operationId: provisionSSLCertificates responses: 200: @@ -497,7 +514,9 @@ paths: get: tags: - DNS - description: Retrieve secondary nameservers. + summary: Get DNS secondary nameserver + description: | + Returns a list of nameserver hostnames. operationId: getDnsSecondaryNameserver responses: 200: @@ -515,7 +534,9 @@ paths: post: tags: - DNS - description: Add secondary nameservers. + summary: Add DNS secondary nameserver + description: | + Adds one or more secondary nameservers. operationId: addDnsSecondaryNameserver requestBody: required: true @@ -547,7 +568,8 @@ paths: get: tags: - DNS - description: Retrieve DNS zones. + summary: Get DNS zones + description: Returns an array of all managed top-level domains. operationId: getDnsZones responses: 200: @@ -566,7 +588,8 @@ paths: post: tags: - DNS - description: Update DNS, which involves creating zone files and restarting `nsd`. + summary: Update DNS + description: Updates the DNS. Involves creating zone files and restarting `nsd`. operationId: updateDns requestBody: required: true @@ -597,7 +620,8 @@ paths: get: tags: - DNS - description: Retrieve all custom DNS records. + summary: Get DNS custom records + description: Returns all custom DNS records. operationId: getDnsCustomRecords responses: 200: @@ -612,14 +636,14 @@ paths: text/html: schema: type: string - /dns/custom/{domain}/{type}: + /dns/custom/{qname}/{type}: parameters: - in: path - name: domain + name: qname schema: $ref: '#/components/schemas/Hostname' required: true - description: DNS record domain + description: DNS record query name - in: path name: type schema: @@ -629,8 +653,9 @@ paths: get: tags: - DNS - description: Get DNS records for domain and type. - operationId: getDnsCustomRecordsForDomainAndType + summary: Get DNS custom records + description: Returns all custom records for the specified query name and type. + operationId: getDnsCustomRecordsForQNameAndType responses: 200: description: Successful operation @@ -647,7 +672,8 @@ paths: post: tags: - DNS - description: Add a custom DNS record. + summary: Add DNS custom record + description: Adds a custom DNS record for the specified query name and type. operationId: addDnsCustomRecord requestBody: $ref: '#/components/requestBodies/DNSCustomRecordRequest' @@ -674,7 +700,8 @@ paths: put: tags: - DNS - description: Update a custom DNS record. + summary: Update DNS custom record + description: Updates an existing DNS custom record value for the specified qname and type. operationId: updateDnsCustomRecord requestBody: $ref: '#/components/requestBodies/DNSCustomRecordRequest' @@ -701,7 +728,8 @@ paths: delete: tags: - DNS - description: Remove a custom DNS record. + summary: Remove DNS custom record + description: Removes a DNS custom record for the specified domain, type & value. operationId: removeDnsCustomRecord requestBody: $ref: '#/components/requestBodies/DNSCustomRecordRequest' @@ -725,19 +753,20 @@ paths: text/html: schema: type: string - /dns/custom/{domain}: + /dns/custom/{qname}: parameters: - in: path - name: domain + name: qname schema: $ref: '#/components/schemas/Hostname' required: true - description: DNS record domain. + description: DNS query name. get: tags: - DNS - description: Get DNS A records for domain. - operationId: getDnsCustomRecordsForDomainAndTypeA + summary: Get DNS custom A records + description: Returns all custom A records for the specified query name. + operationId: getDnsCustomARecordsForQName responses: 200: description: Successful operation @@ -754,8 +783,9 @@ paths: post: tags: - DNS - description: Add a custom DNS A record. - operationId: addDnsCustomRecordForTypeA + summary: Add DNS custom A record + description: Adds a custom DNS A record for the specified query name. + operationId: addDnsCustomARecord requestBody: $ref: '#/components/requestBodies/DNSCustomRecordRequest' responses: @@ -781,8 +811,9 @@ paths: put: tags: - DNS - description: Update a custom DNS A record. - operationId: updateDnsCustomRecordForTypeA + summary: Update DNS custom A record + description: Updates an existing DNS custom A record value for the specified qname. + operationId: updateDnsCustomARecord requestBody: $ref: '#/components/requestBodies/DNSCustomRecordRequest' responses: @@ -808,8 +839,9 @@ paths: delete: tags: - DNS - description: Remove a custom DNS A record. - operationId: removeDnsCustomRecordForTypeA + summary: Remove DNS custom A record + description: Removes a DNS custom A record for the specified domain & value. + operationId: removeDnsCustomARecord requestBody: $ref: '#/components/requestBodies/DNSCustomRecordRequest' responses: @@ -836,7 +868,8 @@ paths: get: tags: - DNS - description: Retrieve all DNS records. + summary: Get DNS dump + description: Returns all DNS records. operationId: getDnsDump responses: 200: @@ -866,7 +899,8 @@ paths: get: tags: - Mail - description: Retrieve all mail users. + summary: Get mail users + description: Returns all mail users. operationId: getMailUsers parameters: - in: query @@ -894,7 +928,8 @@ paths: post: tags: - Mail - description: Add a new mail user. + summary: Add mail user + description: Adds a new mail user. operationId: addMailUser requestBody: required: true @@ -926,7 +961,8 @@ paths: post: tags: - Mail - description: Remove a mail user. + summary: Remove mail user + description: Removes an existing mail user. operationId: removeMailUser requestBody: required: true @@ -958,7 +994,8 @@ paths: post: tags: - Mail - description: Add a privilege to a mail user. + summary: Add mail user privilege + description: Adds a privilege to an existing mail user. operationId: addMailUserPrivilege requestBody: required: true @@ -990,7 +1027,8 @@ paths: post: tags: - Mail - description: Remove a privilege from a mail user. + summary: Remove mail user privilege + description: Removes a privilege from an existing mail user. operationId: removeMailUserPrivilege requestBody: required: true @@ -1022,7 +1060,8 @@ paths: post: tags: - Mail - description: Set a password for a user. + summary: Set mail user password + description: Sets a password for an existing mail user. operationId: setMailUserPassword requestBody: required: true @@ -1054,7 +1093,8 @@ paths: get: tags: - Mail - description: Retrieve privileges for a user. + summary: Get mail user privileges + description: Returns all privileges for an existing mail user. operationId: getMailUserPrivileges parameters: - in: query @@ -1079,7 +1119,8 @@ paths: get: tags: - Mail - description: Retrieve all mail domains. + summary: Get mail domains + description: Returns all mail domains. operationId: getMailDomains responses: 200: @@ -1098,7 +1139,8 @@ paths: get: tags: - Mail - description: Retrieve all mail aliases. + summary: Get mail aliases + description: Returns all mail aliases. operationId: getMailAliases parameters: - in: query @@ -1128,8 +1170,9 @@ paths: post: tags: - Mail + summary: Upsert mail alias description: | - Add or update a mail alias. If updating, you need to set `update_if_exists: 1`. + Adds or updates a mail alias. If updating, you need to set `update_if_exists: 1`. operationId: upsertMailAlias requestBody: required: true @@ -1161,7 +1204,8 @@ paths: post: tags: - Mail - description: Remove a mail alias. + summary: Remove mail alias + description: Removes a mail alias. operationId: removeMailAlias requestBody: required: true @@ -1193,7 +1237,8 @@ paths: get: tags: - Web - description: Retrieve all static web domains. + summary: Get web domains + description: Returns all static web domains. operationId: getWebDomains responses: 200: @@ -1214,7 +1259,8 @@ paths: post: tags: - Web - description: Update static websites, used for updating domain root directories. + summary: Update web + description: Updates static websites, used for updating domain root directories. operationId: updateWeb responses: 200: