From b117df987559d91eb7a043a95486265dbb4caf7f Mon Sep 17 00:00:00 2001 From: Medformatik Date: Sat, 21 Sep 2024 12:46:51 +0200 Subject: [PATCH] document GET email endpoint This commit documents the GET email API endpoint in the `openapi.yaml` file and contains some formatting of the file as well as changes to descriptions, summaries and the introduction. In the introduction I've documented how to set the environment variables because adding them to the compose file as it said here before doesn't work. --- static/openapi.yaml | 335 ++++++++++++++++++++++++-------------------- 1 file changed, 180 insertions(+), 155 deletions(-) diff --git a/static/openapi.yaml b/static/openapi.yaml index 4c4147b..9b02a8f 100644 --- a/static/openapi.yaml +++ b/static/openapi.yaml @@ -1,39 +1,33 @@ openapi: 3.0.0 info: description: >- - docker-mailserver, or DMS for short, is a production-ready fullstack but simple mail server - (SMTP, IMAP, LDAP, Anti-spam, Anti-virus, etc.). It employs only configuration files, no SQL database. - The image is focused around the slogan "Keep it simple and versioned". + docker-mailserver is a production-ready fullstack but simple mail server (SMTP, IMAP, LDAP, Antispam, Antivirus, etc.) running inside a container. - docker-mailserver-webapi is a REST API that helps you efficiently - manage your docker-mailserver configuration. - It uses docker-mailserver setup.sh as a bridge for managing configurations. - - - In order to use this API you need a API key and add your IP - address to the whitelist of allowed IPs this can be done by add new environment variable - WEB_API_KEY and WEB_API_WHITELISTED_IP in your compose file. + docker-mailserver-webapi is a REST API that helps you efficiently manage your docker-mailserver configuration. It uses the docker-mailserver `setup.sh` as a bridge for managing configurations. + + In order to use this API, you need to add an API key and your IP address to a whitelist of allowed IPs. + Create a [*`webapi.env`*](https://github.com/bramanda48/docker-mailserver-webapi/blob/master/.env.example) file with the variables from this [example file](https://github.com/bramanda48/docker-mailserver-webapi/blob/master/.env.example) and bind it to the Docker container under `/tmp/docker-mailserver/webapi/.env`. title: Docker Mailserver - Web API version: "1.0.0" servers: - url: "{protocol}://{host}:{port}/{baseUrl}" - description: '' + description: "" variables: protocol: default: http enum: - http - https - description: The protocol used to access the server. + description: The protocol used to make requests to the API. host: default: localhost description: The hostname or IP address of the server. port: default: "3000" - description: The port number on which the server is listening for requests + description: The port number on which the API is listening for requests. baseUrl: default: "" description: The base URL path for all API endpoints. This can be used to group related endpoints together under a common path. @@ -47,34 +41,31 @@ components: security: - ApiKeyAuth: [] - + tags: - - name: DKIM (DomainKeys Identified Mail) - description: Manage DKIM Keys - - name: Mail Account - description: You can manage mail account. + - name: DKIM + description: Manage DKIM (DomainKeys Identified Mail) Keys + - name: Accounts + description: Manage mail accounts. - name: Aliases - description: You can manage aliases. + description: Manage mail account aliases. - name: Quota - description: You can manage quota. + description: Manage mail account quotas. - name: Dovecot - description: You can manage dovecot master and etc. - - name: Relay - description: You can manage relay-host service. - - name: Fail2ban - description: Manage netfilter fail2ban. + description: Manage the Dovecot master account. + - name: Relays + description: Manage relay-host services. + - name: Fail2Ban + description: Manage Fail2Ban IP bans. - name: Logs - description: Manage docker mailserver logs. - + description: Get logs from various services. + paths: - ############################################################################ - # DKIM Manager - ############################################################################ /api/v1/config/dkim: post: tags: - - DKIM (DomainKeys Identified Mail) - summary: Creates DKIM keys and configures them within DMS. + - DKIM + summary: Creates DKIM keys and configures them within docker-mailserver. operationId: setup-dkim requestBody: description: | @@ -101,7 +92,7 @@ paths: selector: type: string example: "mail" - domain: + domain: type: string example: "example.com" keytype: @@ -119,25 +110,88 @@ paths: responses: 200: description: Success - - - ############################################################################ - # Mail Account - ############################################################################ + /api/v1/email: - get: + get: tags: - - Mail Account - summary: Get all registered mail account. + - Accounts + summary: Get all registered mail accounts. operationId: get-email responses: 200: - description: Success - - post: + description: Response contains all registered mail accounts. + content: + application/json: + schema: + type: object + properties: + statusCode: + type: integer + example: 200 + metadata: + type: object + properties: + request: + type: object + properties: + timestamp: + type: string + format: date-time + example: "2024-09-19T14:56:37.706Z" + method: + type: string + example: "GET" + path: + type: string + example: "/api/v1/email" + pagination: + type: object + nullable: true + data: + type: array + items: + type: object + properties: + email: + type: string + example: "user@example.com" + password: + type: string + description: Password in SHA512 + alias: + type: array + items: + type: object + properties: + emailAlias: + type: string + example: "alias@example.com" + quota: + type: object + properties: + quotaUsed: + type: integer + example: 0 + quotaUsedPercent: + type: integer + example: 0 + quota: + type: integer + example: 0 + restriction: + type: object + properties: + send: + type: boolean + example: false + receive: + type: boolean + example: false + + post: tags: - - Mail Account - summary: Add a new mail account (email address). + - Accounts + summary: Create a new mail account. operationId: add-email requestBody: required: true @@ -155,11 +209,11 @@ paths: responses: 200: description: Success - - patch: + + patch: tags: - - Mail Account - summary: Update the password for a mail account. + - Accounts + summary: Update the password of a mail account. operationId: update-email requestBody: required: true @@ -177,14 +231,13 @@ paths: responses: 200: description: Success - - delete: + + delete: tags: - - Mail Account - summary: Delete a mail account, including associated data (aliases, quotas) and - optionally the mailbox storage for that account. + - Accounts + summary: Delete a mail account including associated data (aliases, quotas) and optionally the mailbox storage for that account. operationId: delete-email - parameters: + parameters: - in: query name: email schema: @@ -195,15 +248,14 @@ paths: responses: 200: description: Success - - + /api/v1/email/restrict: - get: + get: tags: - - Mail Account + - Accounts summary: Display restricted mail accounts. operationId: get-email-restrict - parameters: + parameters: - in: query name: email schema: @@ -214,11 +266,11 @@ paths: responses: 200: description: Success - - post: + + post: tags: - - Mail Account - summary: Add a mail account to restricted list. + - Accounts + summary: Add a mail account to the restricted list. operationId: add-email-restrict requestBody: description: | @@ -244,13 +296,13 @@ paths: responses: 200: description: Success - - delete: + + delete: tags: - - Mail Account + - Accounts summary: Remove a mail account from the restricted list. operationId: delete-email-restrict - parameters: + parameters: - in: query name: access schema: @@ -270,13 +322,9 @@ paths: responses: 200: description: Success - - - ############################################################################ - # Alias - ############################################################################ + /api/v1/alias: - post: + post: tags: - Aliases summary: Add an alias for a recipient (a mail account). @@ -299,14 +347,14 @@ paths: responses: 200: description: Success - - delete: + + delete: tags: - Aliases - summary: Remove a mail account (the recipient) from an existing alias. + summary: Remove a mail account (the recipient) from an existing alias. operationId: delete-alias description: "If the alias has no more recipients, the alias will also be removed." - parameters: + parameters: - in: query name: emailAlias schema: @@ -324,16 +372,12 @@ paths: responses: 200: description: Success - - - ############################################################################ - # Quota - ############################################################################ + /api/v1/quota: - patch: + patch: tags: - Quota - summary: Set a quota (storage limit) for an existing mail account. + summary: Set a quota (storage limit) for an existing mail account. operationId: update-quota requestBody: description: | @@ -357,13 +401,13 @@ paths: responses: 200: description: Success - - delete: + + delete: tags: - Quota summary: Remove any quota set for an existing mail account. operationId: delete-quota - parameters: + parameters: - in: query name: email schema: @@ -374,25 +418,21 @@ paths: responses: 200: description: Success - - - ############################################################################ - # Dovecot - ############################################################################ + /api/v1/dovecot/master: - get: + get: tags: - Dovecot - summary: Get list dovecot-master account. + summary: Get a list of all Dovecot master accounts. operationId: get-dovecot-master responses: 200: description: Success - - post: + + post: tags: - Dovecot - summary: Add a new dovecot-master account (for POP3/IMAP administration). + summary: Add a new Dovecot master account (for POP3/IMAP administration). operationId: add-dovecot-master requestBody: required: true @@ -410,11 +450,11 @@ paths: responses: 200: description: Success - - patch: + + patch: tags: - Dovecot - summary: Update the password for a dovecot-master account. + summary: Update the password for a Dovecot master account. operationId: update-dovecot-master requestBody: required: true @@ -432,13 +472,13 @@ paths: responses: 200: description: Success - - delete: + + delete: tags: - Dovecot - summary: Remove a dovecot-master account. + summary: Delete a Dovecot master account. operationId: delete-dovecot-master - parameters: + parameters: - in: query name: username schema: @@ -451,17 +491,12 @@ paths: responses: 200: description: Success - - - - ############################################################################ - # Relay - ############################################################################ + /api/v1/relay/add-auth: - post: + post: tags: - - Relay - summary: Add credentials to authenticate to a relay-host service. + - Relays + summary: Add credentials to authenticate to a relay-host service. operationId: relay-add-auth requestBody: required: true @@ -482,20 +517,19 @@ paths: responses: 200: description: Success - - + /api/v1/relay/add-domain: - post: + post: tags: - - Relay - summary: Add domain to relay-host service. + - Relays + summary: Add a domain to a relay-host service. operationId: relay-add-domain description: | Add a relay-host where mail sent from mail accounts of the provided, domain will be relayed through to their destination. - + If a port is not provided it will default to 25. - + If the relay-host requires authentication, use the 'setup relay add-auth' command after adding the relay-host. requestBody: @@ -517,18 +551,17 @@ paths: responses: 200: description: Success - - + /api/v1/relay/exclude-domain: - post: + post: tags: - - Relay - summary: Exclude the domain from relay-host service. + - Relays + summary: Exclude a domain from a relay-host service. operationId: relay-exclude-domain description: | When a default relay-host is configured (via ENV), the default behaviour is to relay all your mail accounts outgoing mail through that service. - + This command allows to opt-out from that default behaviour by excluding all mail accounts belonging to a hosted domain you specify. requestBody: @@ -544,28 +577,24 @@ paths: responses: 200: description: Success - - - ############################################################################ - # Fail2ban - ############################################################################ + /api/v1/fail2ban: - get: + get: tags: - - Fail2ban - summary: Get all banned IP Address. + - Fail2Ban + summary: Get all banned IP addresses. operationId: get-fail2ban responses: 200: description: Success - + /api/v1/fail2ban/ban/{ip}: - post: + post: tags: - - Fail2ban - summary: Add IP Address to the custom jail. + - Fail2Ban + summary: Add an IP address to the custom jail. operationId: ban-fail2ban - parameters: + parameters: - in: path name: ip schema: @@ -576,14 +605,14 @@ paths: responses: 200: description: Success - + /api/v1/fail2ban/unban/{ip}: - post: + post: tags: - - Fail2ban - summary: Unban IP Address. + - Fail2Ban + summary: Unban and IP address. operationId: unban-fail2ban - parameters: + parameters: - in: path name: ip schema: @@ -595,17 +624,13 @@ paths: 200: description: Success - - ############################################################################ - # Logs - ############################################################################ /api/v1/logs/fail2ban: - get: + get: tags: - Logs - summary: Get latest fail2ban logs. + summary: Get latest Fail2Ban logs. operationId: get-logs-fail2ban - parameters: + parameters: - in: query name: limit schema: @@ -615,4 +640,4 @@ paths: description: "Number of lines displayed (Default: 25)." responses: 200: - description: Success \ No newline at end of file + description: Success