Merge pull request #14297 from jwhonce/wip/swagger

Swagger refactor/cleanup

4 files changed, 61 insertions, 169 deletions

diff --git a/pkg/domain/entities/filters.go b/pkg/domain/entities/filters.go
index 2ddbffbcd..a42c5cd24 100644
--- a/pkg/domain/entities/filters.go
+++ b/pkg/domain/entities/filters.go
@@ -15,23 +15,17 @@ type Named interface {
 	Name() string
 }
 
-// Named interface allows filters to access Name() of object
+// Names interface allows filters to access Name() of object
 type Names interface {
 	Names() []string
 }
 
-// IDOrName interface allows filters to access ID() or Name() of object
+// IDOrNamed interface allows filters to access ID() or Name() of object
 type IDOrNamed interface {
 	Identifier
 	Named
 }
 
-// IDOrName interface allows filters to access ID() or Names() of object
-type IDOrNames interface {
-	Identifier
-	Names
-}
-
 type ImageFilter func(Image) bool
 type VolumeFilter func(Volume) bool
 type ContainerFilter func(Container) bool
diff --git a/pkg/domain/entities/pods.go b/pkg/domain/entities/pods.go
index a19edcbf0..9cbbe2bf1 100644
--- a/pkg/domain/entities/pods.go
+++ b/pkg/domain/entities/pods.go
@@ -20,15 +20,15 @@ type PodKillOptions struct {
 
 type PodKillReport struct {
 	Errs []error
-	Id   string //nolint
+	Id   string // nolint
 }
 
 type ListPodsReport struct {
 	Cgroup     string
 	Containers []*ListPodContainer
 	Created    time.Time
-	Id         string //nolint
-	InfraId    string //nolint
+	Id         string // nolint
+	InfraId    string // nolint
 	Name       string
 	Namespace  string
 	// Network names connected to infra container
@@ -38,7 +38,7 @@ type ListPodsReport struct {
 }
 
 type ListPodContainer struct {
-	Id     string //nolint
+	Id     string // nolint
 	Names  string
 	Status string
 }
@@ -50,7 +50,7 @@ type PodPauseOptions struct {
 
 type PodPauseReport struct {
 	Errs []error
-	Id   string //nolint
+	Id   string // nolint
 }
 
 type PodunpauseOptions struct {
@@ -60,7 +60,7 @@ type PodunpauseOptions struct {
 
 type PodUnpauseReport struct {
 	Errs []error
-	Id   string //nolint
+	Id   string // nolint
 }
 
 type PodStopOptions struct {
@@ -72,7 +72,7 @@ type PodStopOptions struct {
 
 type PodStopReport struct {
 	Errs []error
-	Id   string //nolint
+	Id   string // nolint
 }
 
 type PodRestartOptions struct {
@@ -82,7 +82,7 @@ type PodRestartOptions struct {
 
 type PodRestartReport struct {
 	Errs []error
-	Id   string //nolint
+	Id   string // nolint
 }
 
 type PodStartOptions struct {
@@ -92,7 +92,7 @@ type PodStartOptions struct {
 
 type PodStartReport struct {
 	Errs []error
-	Id   string //nolint
+	Id   string // nolint
 }
 
 type PodRmOptions struct {
@@ -105,7 +105,7 @@ type PodRmOptions struct {
 
 type PodRmReport struct {
 	Err error
-	Id  string //nolint
+	Id  string // nolint
 }
 
 // PddSpec is an abstracted version of PodSpecGen designed to eventually accept options
@@ -287,7 +287,7 @@ func NewInfraContainerCreateOptions() ContainerCreateOptions {
 }
 
 type PodCreateReport struct {
-	Id string //nolint
+	Id string // nolint
 }
 
 func (p *PodCreateOptions) CPULimits() *specs.LinuxCPU {
@@ -389,7 +389,7 @@ type PodPruneOptions struct {
 
 type PodPruneReport struct {
 	Err error
-	Id  string //nolint
+	Id  string // nolint
 }
 
 type PodTopOptions struct {
@@ -437,16 +437,33 @@ type PodStatsOptions struct {
 
 // PodStatsReport includes pod-resource statistics data.
 type PodStatsReport struct {
-	CPU           string
-	MemUsage      string
+	// Percentage of CPU utilized by pod
+	// example: 75.5%
+	CPU string
+	// Humanized Memory usage and maximum
+	// example: 12mb / 24mb
+	MemUsage string
+	// Memory usage and maximum in bytes
+	// example: 1,000,000 / 4,000,000
 	MemUsageBytes string
-	Mem           string
-	NetIO         string
-	BlockIO       string
-	PIDS          string
-	Pod           string
-	CID           string
-	Name          string
+	// Percentage of Memory utilized by pod
+	// example: 50.5%
+	Mem string
+	// Network usage inbound + outbound
+	NetIO string
+	// Humanized disk usage read + write
+	BlockIO string
+	// Container PID
+	PIDS string
+	// Pod ID
+	// example: 62310217a19e
+	Pod string
+	// Container ID
+	// example: e43534f89a7d
+	CID string
+	// Pod Name
+	// example: elastic_pascal
+	Name string
 }
 
 // ValidatePodStatsOptions validates the specified slice and options. Allows
@@ -475,7 +492,7 @@ func ValidatePodStatsOptions(args []string, options *PodStatsOptions) error {
 	}
 }
 
-// Converts PodLogOptions to ContainerLogOptions
+// PodLogsOptionsToContainerLogsOptions converts PodLogOptions to ContainerLogOptions
 func PodLogsOptionsToContainerLogsOptions(options PodLogsOptions) ContainerLogsOptions {
 	// PodLogsOptions are similar but contains few extra fields like ctrName
 	// So cast other values as is so we can re-use the code
diff --git a/pkg/domain/entities/types.go b/pkg/domain/entities/types.go
index bed3183e9..5ae8a4931 100644
--- a/pkg/domain/entities/types.go
+++ b/pkg/domain/entities/types.go
@@ -9,6 +9,7 @@ import (
 	"github.com/containers/podman/v4/libpod/events"
 	"github.com/containers/podman/v4/pkg/specgen"
 	"github.com/containers/storage/pkg/archive"
+	dockerAPI "github.com/docker/docker/api/types"
 )
 
 type Container struct {
@@ -26,8 +27,10 @@ type Report struct {
 
 type PodDeleteReport struct{ Report }
 
-type VolumeDeleteOptions struct{}
-type VolumeDeleteReport struct{ Report }
+type (
+	VolumeDeleteOptions struct{}
+	VolumeDeleteReport  struct{ Report }
+)
 
 type NetFlags struct {
 	AddHosts     []string `json:"add-host,omitempty"`
@@ -59,7 +62,7 @@ type NetOptions struct {
 	NetworkOptions map[string][]string `json:"network_options,omitempty"`
 }
 
-// All CLI inspect commands and inspect sub-commands use the same options
+// InspectOptions all CLI inspect commands and inspect sub-commands use the same options
 type InspectOptions struct {
 	// Format - change the output to JSON or a Go template.
 	Format string `json:",omitempty"`
@@ -73,7 +76,7 @@ type InspectOptions struct {
 	All bool `json:",omitempty"`
 }
 
-// All API and CLI diff commands and diff sub-commands use the same options
+// DiffOptions all API and CLI diff commands and diff sub-commands use the same options
 type DiffOptions struct {
 	Format  string          `json:",omitempty"` // CLI only
 	Latest  bool            `json:",omitempty"` // API and CLI, only supported by containers
@@ -115,3 +118,11 @@ type BuildReport struct {
 	// ID of the image.
 	ID string
 }
+
+type IDOrNameResponse struct {
+	// The Id or Name of an object
+	IDOrName string
+}
+
+// swagger:model
+type IDResponse dockerAPI.IDResponse
diff --git a/pkg/domain/entities/volumes.go b/pkg/domain/entities/volumes.go
index f2e60a0db..84f85b83f 100644
--- a/pkg/domain/entities/volumes.go
+++ b/pkg/domain/entities/volumes.go
@@ -4,75 +4,10 @@ import (
 	"net/url"
 
 	"github.com/containers/podman/v4/libpod/define"
-	docker_api_types "github.com/docker/docker/api/types"
-	docker_api_types_volume "github.com/docker/docker/api/types/volume"
 )
 
-// Volume volume
-// swagger:model Volume
-type volume struct {
-
-	// Date/Time the volume was created.
-	CreatedAt string `json:"CreatedAt,omitempty"`
-
-	// Name of the volume driver used by the volume.
-	// Required: true
-	Driver string `json:"Driver"`
-
-	// User-defined key/value metadata.
-	// Required: true
-	Labels map[string]string `json:"Labels"`
-
-	// Mount path of the volume on the host.
-	// Required: true
-	Mountpoint string `json:"Mountpoint"`
-
-	// Name of the volume.
-	// Required: true
-	Name string `json:"Name"`
-
-	// The driver specific options used when creating the volume.
-	//
-	// Required: true
-	Options map[string]string `json:"Options"`
-
-	// The level at which the volume exists. Either `global` for cluster-wide,
-	// or `local` for machine level.
-	//
-	// Required: true
-	Scope string `json:"Scope"`
-
-	// Low-level details about the volume, provided by the volume driver.
-	// Details are returned as a map with key/value pairs:
-	// `{"key":"value","key2":"value2"}`.
-	//
-	// The `Status` field is optional, and is omitted if the volume driver
-	// does not support this feature.
-	//
-	Status map[string]interface{} `json:"Status,omitempty"`
-
-	// usage data
-	UsageData *VolumeUsageData `json:"UsageData,omitempty"`
-}
-
-type VolumeUsageData struct {
-
-	// The number of containers referencing this volume. This field
-	// is set to `-1` if the reference-count is not available.
-	//
-	// Required: true
-	RefCount int64 `json:"RefCount"`
-
-	// Amount of disk space used by the volume (in bytes). This information
-	// is only available for volumes created with the `"local"` volume
-	// driver. For volumes created with other volume drivers, this field
-	// is set to `-1` ("not available")
-	//
-	// Required: true
-	Size int64 `json:"Size"`
-}
-
-// swagger:model VolumeCreate
+// VolumeCreateOptions provides details for creating volumes
+// swagger:model
 type VolumeCreateOptions struct {
 	// New volume's name. Can be left blank
 	Name string `schema:"name"`
@@ -86,11 +21,6 @@ type VolumeCreateOptions struct {
 	Options map[string]string `schema:"opts"`
 }
 
-type IDOrNameResponse struct {
-	// The Id or Name of an object
-	IDOrName string
-}
-
 type VolumeConfigResponse struct {
 	define.InspectVolumeData
 }
@@ -103,7 +33,7 @@ type VolumeRmOptions struct {
 
 type VolumeRmReport struct {
 	Err error
-	Id  string //nolint
+	Id  string // nolint
 }
 
 type VolumeInspectReport struct {
@@ -124,74 +54,14 @@ type VolumeListReport struct {
 	VolumeConfigResponse
 }
 
-// VolumeListBody Volume list response
-// swagger:model VolumeListBody
-type VolumeListBody struct {
-	Volumes []docker_api_types_volume.VolumeListOKBody
-}
-
-// Volume list response
-// swagger:response VolumeListResponse
-type SwagVolumeListResponse struct {
-	// in:body
-	Body struct {
-		VolumeListBody
-	}
-}
-
 /*
  * Docker API compatibility types
  */
 
-// swagger:model DockerVolumeCreate
-type DockerVolumeCreate VolumeCreateBody
-
-// This response definition is used for both the create and inspect endpoints
-// swagger:response DockerVolumeInfoResponse
-type SwagDockerVolumeInfoResponse struct {
-	// in:body
-	Body struct {
-		volume
-	}
-}
-
-// Volume prune response
-// swagger:response DockerVolumePruneResponse
-type SwagDockerVolumePruneResponse struct {
-	// in:body
-	Body struct {
-		docker_api_types.VolumesPruneReport
-	}
-}
-
-// VolumeCreateBody Volume configuration
-// swagger:model VolumeCreateBody
-type VolumeCreateBody struct {
-
-	// Name of the volume driver to use.
-	// Required: true
-	Driver string `json:"Driver"`
-
-	// A mapping of driver options and values. These options are
-	// passed directly to the driver and are driver specific.
-	//
-	// Required: true
-	DriverOpts map[string]string `json:"DriverOpts"`
-
-	// User-defined key/value metadata.
-	// Required: true
-	Labels map[string]string `json:"Labels"`
-
-	// The new volume's name. If not specified, Docker generates a name.
-	//
-	// Required: true
-	Name string `json:"Name"`
-}
-
 // VolumeMountReport describes the response from volume mount
 type VolumeMountReport struct {
 	Err  error
-	Id   string //nolint
+	Id   string // nolint
 	Name string
 	Path string
 }
@@ -199,5 +69,5 @@ type VolumeMountReport struct {
 // VolumeUnmountReport describes the response from umounting a volume
 type VolumeUnmountReport struct {
 	Err error
-	Id  string //nolint
+	Id  string // nolint
 }