Add summaries & update version to 0.47

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.
+      summary: Get DNS custom records
-      operationId: getDnsCustomRecordsForDomainAndType
+      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.
+      summary: Get DNS custom A records
-      operationId: getDnsCustomRecordsForDomainAndTypeA
+      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.
+      summary: Add DNS custom A record
-      operationId: addDnsCustomRecordForTypeA
+      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.
+      summary: Update DNS custom A record
-      operationId: updateDnsCustomRecordForTypeA
+      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.
+      summary: Remove DNS custom A record
-      operationId: removeDnsCustomRecordForTypeA
+      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: