Merge pull request moby#43332 from thaJeztah/api_swagger_move_definit…

…ions

api: swagger: use explicit definitions for some response types, and move examples per-field

api/server/router/volume/backend.go

@@ -7,14 +7,15 @@ import (
 	// TODO return types need to be refactored into pkg
 	"github.com/docker/docker/api/types"
 	"github.com/docker/docker/api/types/filters"
+	"github.com/docker/docker/api/types/volume"
 )
 
 // Backend is the methods that need to be implemented to provide
 // volume specific functionality
 type Backend interface {
-	List(ctx context.Context, filter filters.Args) ([]*types.Volume, []string, error)
-	Get(ctx context.Context, name string, opts ...opts.GetOption) (*types.Volume, error)
-	Create(ctx context.Context, name, driverName string, opts ...opts.CreateOption) (*types.Volume, error)
+	List(ctx context.Context, filter filters.Args) ([]*volume.Volume, []string, error)
+	Get(ctx context.Context, name string, opts ...opts.GetOption) (*volume.Volume, error)
+	Create(ctx context.Context, name, driverName string, opts ...opts.CreateOption) (*volume.Volume, error)
 	Remove(ctx context.Context, name string, opts ...opts.RemoveOption) error
 	Prune(ctx context.Context, pruneFilters filters.Args) (*types.VolumesPruneReport, error)
 }

api/swagger.yaml

@@ -2069,6 +2069,25 @@ definitions:
           com.example.some-label: "some-value"
           com.example.some-other-label: "some-other-value"
 
+  VolumeListResponse:
+    type: "object"
+    title: "VolumeListResponse"
+    x-go-name: "VolumeListOKBody"
+    description: "Volume list response"
+    properties:
+      Volumes:
+        type: "array"
+        description: "List of volumes"
+        items:
+          $ref: "#/definitions/Volume"
+      Warnings:
+        type: "array"
+        description: |
+          Warnings that occurred when fetching the list of volumes.
+        items:
+          type: "string"
+        example: []
+
   Network:
     type: "object"
     properties:
@@ -9145,24 +9164,7 @@ paths:
         200:
           description: "Summary volume data that matches the query"
           schema:
-            type: "object"
-            title: "VolumeListResponse"
-            description: "Volume list response"
-            required: [Volumes, Warnings]
-            properties:
-              Volumes:
-                type: "array"
-                x-nullable: false
-                description: "List of volumes"
-                items:
-                  $ref: "#/definitions/Volume"
-              Warnings:
-                type: "array"
-                x-nullable: false
-                description: |
-                  Warnings that occurred when fetching the list of volumes.
-                items:
-                  type: "string"
+            $ref: "#/definitions/VolumeListResponse"
         500:
           description: "Server error"
           schema:

api/types/deprecated.go

@@ -0,0 +1,14 @@
+package types // import "github.com/docker/docker/api/types"
+
+import "github.com/docker/docker/api/types/volume"
+
+// Volume volume
+//
+// Deprecated: use github.com/docker/docker/api/types/volume.Volume
+type Volume = volume.Volume
+
+// VolumeUsageData Usage details about the volume. This information is used by the
+// `GET /system/df` endpoint, and omitted in other endpoints.
+//
+// Deprecated: use github.com/docker/docker/api/types/volume.VolumeUsageData
+type VolumeUsageData = volume.VolumeUsageData

api/types/types.go

@@ -14,6 +14,7 @@ import (
 	"github.com/docker/docker/api/types/network"
 	"github.com/docker/docker/api/types/registry"
 	"github.com/docker/docker/api/types/swarm"
+	"github.com/docker/docker/api/types/volume"
 	"github.com/docker/go-connections/nat"
 )
 
@@ -686,7 +687,7 @@ type DiskUsage struct {
 	LayersSize  int64
 	Images      []*ImageSummary
 	Containers  []*Container
-	Volumes     []*Volume
+	Volumes     []*volume.Volume
 	BuildCache  []*BuildCache
 	BuilderSize int64 `json:",omitempty"` // Deprecated: deprecated in API 1.38, and no longer used since API 1.40.
 }

api/types/volume.go → api/types/volume/volume.go

@@ -1,4 +1,4 @@
-package types
+package volume
 
 // This file was generated by the swagger tool.
 // Editing this file might prove futile when you re-run the swagger generate command

api/types/volume/volume_list_o_k_body.go

@@ -0,0 +1,18 @@
+package volume
+
+// This file was generated by the swagger tool.
+// Editing this file might prove futile when you re-run the swagger generate command
+
+// VolumeListOKBody VolumeListResponse
+//
+// Volume list response
+// swagger:model VolumeListOKBody
+type VolumeListOKBody struct {
+
+	// List of volumes
+	Volumes []*Volume `json:"Volumes"`
+
+	// Warnings that occurred when fetching the list of volumes.
+	//
+	Warnings []string `json:"Warnings"`
+}

client/interface.go

@@ -173,9 +173,9 @@ type SystemAPIClient interface {
 
 // VolumeAPIClient defines API client methods for the volumes
 type VolumeAPIClient interface {
-	VolumeCreate(ctx context.Context, options volume.VolumeCreateBody) (types.Volume, error)
-	VolumeInspect(ctx context.Context, volumeID string) (types.Volume, error)
-	VolumeInspectWithRaw(ctx context.Context, volumeID string) (types.Volume, []byte, error)
+	VolumeCreate(ctx context.Context, options volume.VolumeCreateBody) (volume.Volume, error)
+	VolumeInspect(ctx context.Context, volumeID string) (volume.Volume, error)
+	VolumeInspectWithRaw(ctx context.Context, volumeID string) (volume.Volume, []byte, error)
 	VolumeList(ctx context.Context, filter filters.Args) (volume.VolumeListOKBody, error)
 	VolumeRemove(ctx context.Context, volumeID string, force bool) error
 	VolumesPrune(ctx context.Context, pruneFilter filters.Args) (types.VolumesPruneReport, error)

client/volume_create.go

@@ -4,18 +4,17 @@ import (
 	"context"
 	"encoding/json"
 
-	"github.com/docker/docker/api/types"
-	volumetypes "github.com/docker/docker/api/types/volume"
+	"github.com/docker/docker/api/types/volume"
 )
 
 // VolumeCreate creates a volume in the docker host.
-func (cli *Client) VolumeCreate(ctx context.Context, options volumetypes.VolumeCreateBody) (types.Volume, error) {
-	var volume types.Volume
+func (cli *Client) VolumeCreate(ctx context.Context, options volume.VolumeCreateBody) (volume.Volume, error) {
+	var vol volume.Volume
 	resp, err := cli.post(ctx, "/volumes/create", nil, options, nil)
 	defer ensureReaderClosed(resp)
 	if err != nil {
-		return volume, err
+		return vol, err
 	}
-	err = json.NewDecoder(resp.body).Decode(&volume)
-	return volume, err
+	err = json.NewDecoder(resp.body).Decode(&vol)
+	return vol, err
 }

client/volume_create_test.go

@@ -10,8 +10,7 @@ import (
 	"strings"
 	"testing"
 
-	"github.com/docker/docker/api/types"
-	volumetypes "github.com/docker/docker/api/types/volume"
+	"github.com/docker/docker/api/types/volume"
 	"github.com/docker/docker/errdefs"
 )
 
@@ -20,7 +19,7 @@ func TestVolumeCreateError(t *testing.T) {
 		client: newMockClient(errorMock(http.StatusInternalServerError, "Server error")),
 	}
 
-	_, err := client.VolumeCreate(context.Background(), volumetypes.VolumeCreateBody{})
+	_, err := client.VolumeCreate(context.Background(), volume.VolumeCreateBody{})
 	if !errdefs.IsSystem(err) {
 		t.Fatalf("expected a Server Error, got %[1]T: %[1]v", err)
 	}
@@ -39,7 +38,7 @@ func TestVolumeCreate(t *testing.T) {
 				return nil, fmt.Errorf("expected POST method, got %s", req.Method)
 			}
 
-			content, err := json.Marshal(types.Volume{
+			content, err := json.Marshal(volume.Volume{
 				Name:       "volume",
 				Driver:     "local",
 				Mountpoint: "mountpoint",
@@ -54,7 +53,7 @@ func TestVolumeCreate(t *testing.T) {
 		}),
 	}
 
-	volume, err := client.VolumeCreate(context.Background(), volumetypes.VolumeCreateBody{
+	vol, err := client.VolumeCreate(context.Background(), volume.VolumeCreateBody{
 		Name:   "myvolume",
 		Driver: "mydriver",
 		DriverOpts: map[string]string{
@@ -64,13 +63,13 @@ func TestVolumeCreate(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	if volume.Name != "volume" {
-		t.Fatalf("expected volume.Name to be 'volume', got %s", volume.Name)
+	if vol.Name != "volume" {
+		t.Fatalf("expected volume.Name to be 'volume', got %s", vol.Name)
 	}
-	if volume.Driver != "local" {
-		t.Fatalf("expected volume.Driver to be 'local', got %s", volume.Driver)
+	if vol.Driver != "local" {
+		t.Fatalf("expected volume.Driver to be 'local', got %s", vol.Driver)
 	}
-	if volume.Mountpoint != "mountpoint" {
-		t.Fatalf("expected volume.Mountpoint to be 'mountpoint', got %s", volume.Mountpoint)
+	if vol.Mountpoint != "mountpoint" {
+		t.Fatalf("expected volume.Mountpoint to be 'mountpoint', got %s", vol.Mountpoint)
 	}
 }

client/volume_inspect.go

@@ -6,33 +6,33 @@ import (
 	"encoding/json"
 	"io"
 
-	"github.com/docker/docker/api/types"
+	"github.com/docker/docker/api/types/volume"
 )
 
 // VolumeInspect returns the information about a specific volume in the docker host.
-func (cli *Client) VolumeInspect(ctx context.Context, volumeID string) (types.Volume, error) {
-	volume, _, err := cli.VolumeInspectWithRaw(ctx, volumeID)
-	return volume, err
+func (cli *Client) VolumeInspect(ctx context.Context, volumeID string) (volume.Volume, error) {
+	vol, _, err := cli.VolumeInspectWithRaw(ctx, volumeID)
+	return vol, err
 }
 
 // VolumeInspectWithRaw returns the information about a specific volume in the docker host and its raw representation
-func (cli *Client) VolumeInspectWithRaw(ctx context.Context, volumeID string) (types.Volume, []byte, error) {
+func (cli *Client) VolumeInspectWithRaw(ctx context.Context, volumeID string) (volume.Volume, []byte, error) {
 	if volumeID == "" {
-		return types.Volume{}, nil, objectNotFoundError{object: "volume", id: volumeID}
+		return volume.Volume{}, nil, objectNotFoundError{object: "volume", id: volumeID}
 	}
 
-	var volume types.Volume
+	var vol volume.Volume
 	resp, err := cli.get(ctx, "/volumes/"+volumeID, nil, nil)
 	defer ensureReaderClosed(resp)
 	if err != nil {
-		return volume, nil, err
+		return vol, nil, err
 	}
 
 	body, err := io.ReadAll(resp.body)
 	if err != nil {
-		return volume, nil, err
+		return vol, nil, err
 	}
 	rdr := bytes.NewReader(body)
-	err = json.NewDecoder(rdr).Decode(&volume)
-	return volume, body, err
+	err = json.NewDecoder(rdr).Decode(&vol)
+	return vol, body, err
 }

client/volume_inspect_test.go

@@ -10,7 +10,7 @@ import (
 	"strings"
 	"testing"
 
-	"github.com/docker/docker/api/types"
+	"github.com/docker/docker/api/types/volume"
 	"github.com/docker/docker/errdefs"
 	"github.com/pkg/errors"
 	"gotest.tools/v3/assert"
@@ -51,7 +51,7 @@ func TestVolumeInspectWithEmptyID(t *testing.T) {
 
 func TestVolumeInspect(t *testing.T) {
 	expectedURL := "/volumes/volume_id"
-	expected := types.Volume{
+	expected := volume.Volume{
 		Name:       "name",
 		Driver:     "driver",
 		Mountpoint: "mountpoint",

client/volume_list_test.go

@@ -10,9 +10,8 @@ import (
 	"strings"
 	"testing"
 
-	"github.com/docker/docker/api/types"
 	"github.com/docker/docker/api/types/filters"
-	volumetypes "github.com/docker/docker/api/types/volume"
+	"github.com/docker/docker/api/types/volume"
 	"github.com/docker/docker/errdefs"
 )
 
@@ -70,8 +69,8 @@ func TestVolumeList(t *testing.T) {
 				if actualFilters != listCase.expectedFilters {
 					return nil, fmt.Errorf("filters not set in URL query properly. Expected '%s', got %s", listCase.expectedFilters, actualFilters)
 				}
-				content, err := json.Marshal(volumetypes.VolumeListOKBody{
-					Volumes: []*types.Volume{
+				content, err := json.Marshal(volume.VolumeListOKBody{
+					Volumes: []*volume.Volume{
 						{
 							Name:   "volume",
 							Driver: "local",

daemon/cluster/executor/backend.go

@@ -14,6 +14,7 @@ import (
 	"github.com/docker/docker/api/types/filters"
 	"github.com/docker/docker/api/types/network"
 	swarmtypes "github.com/docker/docker/api/types/swarm"
+	"github.com/docker/docker/api/types/volume"
 	containerpkg "github.com/docker/docker/container"
 	clustertypes "github.com/docker/docker/daemon/cluster/provider"
 	networkSettings "github.com/docker/docker/daemon/network"
@@ -66,7 +67,7 @@ type Backend interface {
 
 // VolumeBackend is used by an executor to perform volume operations
 type VolumeBackend interface {
-	Create(ctx context.Context, name, driverName string, opts ...volumeopts.CreateOption) (*types.Volume, error)
+	Create(ctx context.Context, name, driverName string, opts ...volumeopts.CreateOption) (*volume.Volume, error)
 }
 
 // ImageBackend is used by an executor to perform image operations

daemon/disk_usage.go

@@ -6,6 +6,7 @@ import (
 
 	"github.com/docker/docker/api/server/router/system"
 	"github.com/docker/docker/api/types"
+	"github.com/docker/docker/api/types/volume"
 	"golang.org/x/sync/errgroup"
 )
 
@@ -64,7 +65,7 @@ func (daemon *Daemon) SystemDiskUsage(ctx context.Context, opts system.DiskUsage
 		})
 	}
 
-	var volumes []*types.Volume
+	var volumes []*volume.Volume
 	if opts.Volumes {
 		eg.Go(func() error {
 			var err error