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