From 2338d582077580281a4ae84318c671dfef5ca015 Mon Sep 17 00:00:00 2001
From: "Max P." <mail@0xMax42.io>
Date: Sun, 12 Oct 2025 14:37:31 +0200
Subject: [PATCH] docs(api): add Docker Volume Plugin API specification

---
 docs/Docker_Volume_Plugin_API.yml | 254 ++++++++++++++++++++++++++++++
 1 file changed, 254 insertions(+)
 create mode 100644 docs/Docker_Volume_Plugin_API.yml

diff --git a/docs/Docker_Volume_Plugin_API.yml b/docs/Docker_Volume_Plugin_API.yml
new file mode 100644
index 0000000..e9bd2a6
--- /dev/null
+++ b/docs/Docker_Volume_Plugin_API.yml
@@ -0,0 +1,254 @@
+openapi: 3.1.0
+info:
+  title: Docker Volume Plugin API
+  version: "1.0.0"
+  description: |
+    Specification of the Docker Volume Driver API.
+    This API is used by the Docker Engine to communicate with external volume plugins.
+servers:
+  - url: http://localhost:8080
+paths:
+  /Plugin.Activate:
+    post:
+      summary: Activate plugin
+      description: Returns the list of implemented interfaces.
+      requestBody:
+        required: false
+      responses:
+        "200":
+          description: Plugin activated successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  Implements:
+                    type: array
+                    items:
+                      type: string
+                required: [Implements]
+
+  /VolumeDriver.Create:
+    post:
+      summary: Create a new volume
+      description: Called when Docker creates a new volume via `docker volume create`.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                Name:
+                  type: string
+                Opts:
+                  type: object
+                  additionalProperties: true
+              required: [Name]
+      responses:
+        "200":
+          description: Volume created successfully
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GenericResponse"
+
+  /VolumeDriver.Remove:
+    post:
+      summary: Remove a volume
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/VolumeRequest"
+      responses:
+        "200":
+          description: Volume removed
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GenericResponse"
+
+  /VolumeDriver.Mount:
+    post:
+      summary: Mount a volume
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/MountRequest"
+      responses:
+        "200":
+          description: Volume mounted
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MountResponse"
+
+  /VolumeDriver.Unmount:
+    post:
+      summary: Unmount a volume
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/MountRequest"
+      responses:
+        "200":
+          description: Volume unmounted
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GenericResponse"
+
+  /VolumeDriver.Path:
+    post:
+      summary: Return mount path for a volume
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/VolumeRequest"
+      responses:
+        "200":
+          description: Volume path
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PathResponse"
+
+  /VolumeDriver.Get:
+    post:
+      summary: Get volume metadata
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/VolumeRequest"
+      responses:
+        "200":
+          description: Volume metadata
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GetResponse"
+
+  /VolumeDriver.List:
+    post:
+      summary: List all volumes
+      requestBody:
+        required: false
+      responses:
+        "200":
+          description: List of managed volumes
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ListResponse"
+
+  /VolumeDriver.Capabilities:
+    post:
+      summary: Return plugin capabilities
+      requestBody:
+        required: false
+      responses:
+        "200":
+          description: Capabilities information
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CapabilitiesResponse"
+
+components:
+  schemas:
+    GenericResponse:
+      type: object
+      properties:
+        Err:
+          type: string
+          description: Empty string indicates success.
+      required: [Err]
+
+    VolumeRequest:
+      type: object
+      properties:
+        Name:
+          type: string
+          description: Volume name.
+      required: [Name]
+
+    MountRequest:
+      type: object
+      properties:
+        Name:
+          type: string
+        ID:
+          type: string
+      required: [Name, ID]
+
+    MountResponse:
+      type: object
+      properties:
+        Mountpoint:
+          type: string
+        Err:
+          type: string
+      required: [Mountpoint, Err]
+
+    PathResponse:
+      type: object
+      properties:
+        Mountpoint:
+          type: string
+        Err:
+          type: string
+      required: [Mountpoint, Err]
+
+    GetResponse:
+      type: object
+      properties:
+        Volume:
+          $ref: "#/components/schemas/Volume"
+        Err:
+          type: string
+      required: [Volume, Err]
+
+    ListResponse:
+      type: object
+      properties:
+        Volumes:
+          type: array
+          items:
+            $ref: "#/components/schemas/Volume"
+        Err:
+          type: string
+      required: [Volumes, Err]
+
+    CapabilitiesResponse:
+      type: object
+      properties:
+        Capabilities:
+          type: object
+          properties:
+            Scope:
+              type: string
+              enum: [local, global]
+        Err:
+          type: string
+      required: [Capabilities, Err]
+
+    Volume:
+      type: object
+      properties:
+        Name:
+          type: string
+        Mountpoint:
+          type: string
+        Status:
+          type: object
+          additionalProperties: true