Add summaries & update version to 0.47

2025-04-19 02:42:15 +00:00 · 2020-08-06 08:22:17 +01:00 · 2020-08-06 08:22:17 +01:00 · 5801e7071a
commit 5801e7071a
parent d4af870145
1 changed files with 102 additions and 56 deletions
--- 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: