5 files changed, 632 insertions, 194 deletions
diff --git a/pkg/api/handlers/swagger/doc.go b/pkg/api/handlers/swagger/doc.go
new file mode 100644
index 000000000..67ede275a
--- /dev/null
+++ b/pkg/api/handlers/swagger/doc.go
@@ -0,0 +1,17 @@
+// Package swagger defines the payloads used by the Podman API
+//
+// - errors.go: declares the errors used in the API. By embedding errors.ErrorModel, more meaningful
+//   comments can be provided for the developer documentation.
+// - models.go: declares the models used in API requests.
+// - responses.go: declares the responses used in the API responses.
+//
+//
+// Notes:
+// 1. As a developer of the Podman API, you are responsible for maintaining the associations between
+//    these models and responses, and the handler code.
+// 2. There are a number of warnings produces when compiling the swagger yaml file. This is expected.
+//    Most are because embedded structs have been discovered but not used in the API declarations.
+// 3. Response and model references that are exported (start with upper-case letter) imply that they
+//    exist outside this package and should be found in the entities package.
+//
+package swagger
diff --git a/pkg/api/handlers/swagger/errors.go b/pkg/api/handlers/swagger/errors.go
new file mode 100644
index 000000000..28e11c9fb
--- /dev/null
+++ b/pkg/api/handlers/swagger/errors.go
@@ -0,0 +1,116 @@
+//nolint:deadcode,unused // these types are used to wire generated swagger to API code
+package swagger
+
+import (
+	"github.com/containers/podman/v4/pkg/errorhandling"
+)
+
+// Error model embedded in swagger:response to aid in documentation generation
+
+// No such image
+// swagger:response
+type imageNotFound struct {
+	// in:body
+	Body errorhandling.ErrorModel
+}
+
+// No such container
+// swagger:response
+type containerNotFound struct {
+	// in:body
+	Body errorhandling.ErrorModel
+}
+
+// No such network
+// swagger:response
+type networkNotFound struct {
+	// in:body
+	Body errorhandling.ErrorModel
+}
+
+// No such exec instance
+// swagger:response
+type execSessionNotFound struct {
+	// in:body
+	Body errorhandling.ErrorModel
+}
+
+// No such volume
+// swagger:response
+type volumeNotFound struct {
+	// in:body
+	Body errorhandling.ErrorModel
+}
+
+// No such pod
+// swagger:response
+type podNotFound struct {
+	// in:body
+	Body errorhandling.ErrorModel
+}
+
+// No such manifest
+// swagger:response
+type manifestNotFound struct {
+	// in:body
+	Body errorhandling.ErrorModel
+}
+
+// Internal server error
+// swagger:response
+type internalError struct {
+	// in:body
+	Body errorhandling.ErrorModel
+}
+
+// Conflict error in operation
+// swagger:response
+type conflictError struct {
+	// in:body
+	Body errorhandling.ErrorModel
+}
+
+// Bad parameter in request
+// swagger:response
+type badParamError struct {
+	// in:body
+	Body errorhandling.ErrorModel
+}
+
+// Container already started
+// swagger:response
+type containerAlreadyStartedError struct {
+	// in:body
+	Body errorhandling.ErrorModel
+}
+
+// Container already stopped
+// swagger:response
+type containerAlreadyStoppedError struct {
+	// in:body
+	Body errorhandling.ErrorModel
+}
+
+// Pod already started
+// swagger:response
+type podAlreadyStartedError struct {
+	// in:body
+	Body errorhandling.ErrorModel
+}
+
+// Pod already stopped
+// swagger:response
+type podAlreadyStoppedError struct {
+	// in:body
+	Body errorhandling.ErrorModel
+}
+
+// Success
+// swagger:response
+type ok struct {
+	// in:body
+	Body struct {
+		// example: OK
+		ok string
+	}
+}
diff --git a/pkg/api/handlers/swagger/models.go b/pkg/api/handlers/swagger/models.go
new file mode 100644
index 000000000..a05e57dff
--- /dev/null
+++ b/pkg/api/handlers/swagger/models.go
@@ -0,0 +1,46 @@
+//nolint:deadcode,unused // these types are used to wire generated swagger to API code
+package swagger
+
+import (
+	"github.com/containers/podman/v4/pkg/domain/entities"
+	"github.com/docker/docker/api/types"
+)
+
+// Details for creating a volume
+// swagger:model
+type volumeCreate 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"`
+}
+
+// Network create
+// swagger:model
+type networkCreate types.NetworkCreateRequest
+
+// Network connect
+// swagger:model
+type networkConnectRequest types.NetworkConnect
+
+// Network disconnect
+// swagger:model
+type networkDisconnectRequest types.NetworkDisconnect
+
+// Network connect
+// swagger:model
+type networkConnectRequestLibpod entities.NetworkConnectOptions
diff --git a/pkg/api/handlers/swagger/responses.go b/pkg/api/handlers/swagger/responses.go
new file mode 100644
index 000000000..55fc1a77f
--- /dev/null
+++ b/pkg/api/handlers/swagger/responses.go
@@ -0,0 +1,453 @@
+//nolint:deadcode,unused // these types are used to wire generated swagger to API code
+package swagger
+
+import (
+	"github.com/containers/common/libnetwork/types"
+	"github.com/containers/image/v5/manifest"
+	"github.com/containers/podman/v4/libpod/define"
+	"github.com/containers/podman/v4/pkg/api/handlers"
+	"github.com/containers/podman/v4/pkg/domain/entities"
+	"github.com/containers/podman/v4/pkg/domain/entities/reports"
+	"github.com/containers/podman/v4/pkg/inspect"
+	dockerAPI "github.com/docker/docker/api/types"
+	dockerVolume "github.com/docker/docker/api/types/volume"
+)
+
+// Image Tree
+// swagger:response
+type treeResponse struct {
+	// in:body
+	Body entities.ImageTreeReport
+}
+
+// Image History
+// swagger:response
+type history struct {
+	// in:body
+	Body handlers.HistoryResponse
+}
+
+// Image Inspect
+// swagger:response
+type imageInspect struct {
+	// in:body
+	Body handlers.ImageInspect
+}
+
+// Image Load
+// swagger:response
+type imagesLoadResponseLibpod struct {
+	// in:body
+	Body entities.ImageLoadReport
+}
+
+// Image Import
+// swagger:response
+type imagesImportResponseLibpod struct {
+	// in:body
+	Body entities.ImageImportReport
+}
+
+// Image Pull
+// swagger:response
+type imagesPullResponseLibpod struct {
+	// in:body
+	Body handlers.LibpodImagesPullReport
+}
+
+// Image Remove
+// swagger:response
+type imagesRemoveResponseLibpod struct {
+	// in:body
+	Body handlers.LibpodImagesRemoveReport
+}
+
+// PlayKube response
+// swagger:response
+type playKubeResponseLibpod struct {
+	// in:body
+	Body entities.PlayKubeReport
+}
+
+// Image Delete
+// swagger:response
+type imageDeleteResponse struct {
+	// in:body
+	Body []struct {
+		Untagged []string `json:"untagged"`
+		Deleted  string   `json:"deleted"`
+	}
+}
+
+// Registry Search
+// swagger:response
+type registrySearchResponse struct {
+	// in:body
+	Body struct {
+		// Index is the image index
+		// example: quay.io
+		Index string
+		// Name is the canonical name of the image
+		// example: docker.io/library/alpine"
+		Name string
+		// Description of the image.
+		Description string
+		// Stars is the number of stars of the image.
+		Stars int
+		// Official indicates if it's an official image.
+		Official string
+		// Automated indicates if the image was created by an automated build.
+		Automated string
+		// Tag is the image tag
+		Tag string
+	}
+}
+
+// Inspect Image
+// swagger:response
+type inspectImageResponseLibpod struct {
+	// in:body
+	Body inspect.ImageData
+}
+
+// Inspect container
+// swagger:response
+type containerInspectResponse struct {
+	// in:body
+	Body dockerAPI.ContainerJSON
+}
+
+// List processes in container
+// swagger:response
+type containerTopResponse struct {
+	// in:body
+	Body handlers.ContainerTopOKBody
+}
+
+// List processes in pod
+// swagger:response
+type podTopResponse struct {
+	// in:body
+	Body handlers.PodTopOKBody
+}
+
+// Pod Statistics
+// swagger:response
+type podStatsResponse struct {
+	// in:body
+	Body []entities.PodStatsReport
+}
+
+// Inspect container
+// swagger:response
+type containerInspectResponseLibpod struct {
+	// in:body
+	Body define.InspectContainerData
+}
+
+// List pods
+// swagger:response
+type podsListResponse struct {
+	// in:body
+	Body []entities.ListPodsReport
+}
+
+// Inspect pod
+// swagger:response
+type podInspectResponse struct {
+	// in:body
+	Body define.InspectPodData
+}
+
+// Volume details
+// swagger:response
+type volumeCreateResponse struct {
+	// in:body
+	Body entities.VolumeConfigResponse
+}
+
+// Healthcheck Results
+// swagger:response
+type healthCheck struct {
+	// in:body
+	Body define.HealthCheckResults
+}
+
+// Version
+// swagger:response
+type versionResponse struct {
+	// in:body
+	Body entities.ComponentVersion
+}
+
+// Disk usage
+// swagger:response
+type systemDiskUsage struct {
+	// in:body
+	Body entities.SystemDfReport
+}
+
+// System Prune results
+// swagger:response
+type systemPruneResponse struct {
+	// in:body
+	Body entities.SystemPruneReport
+}
+
+// Auth response
+// swagger:response
+type systemAuthResponse struct {
+	// in:body
+	Body entities.AuthReport
+}
+
+// Exec Session Inspect
+// swagger:response
+type execSessionInspect struct {
+	// in:body
+	Body define.InspectExecSession
+}
+
+// Image summary for compat API
+// swagger:response
+type imageList struct {
+	// in:body
+	Body []dockerAPI.ImageSummary
+}
+
+// Image summary for libpod API
+// swagger:response
+type imageListLibpod struct {
+	// in:body
+	Body []entities.ImageSummary
+}
+
+// List Containers
+// swagger:response
+type containersList struct {
+	// in:body
+	Body []handlers.Container
+}
+
+// This response definition is used for both the create and inspect endpoints
+// swagger:response
+type volumeInspect struct {
+	// in:body
+	Body dockerAPI.Volume
+}
+
+// Volume prune
+// swagger:response
+type volumePruneResponse struct {
+	// in:body
+	Body dockerAPI.VolumesPruneReport
+}
+
+// Volume List
+// swagger:response
+type volumeList struct {
+	// in:body
+	Body dockerVolume.VolumeListOKBody
+}
+
+// Volume list
+// swagger:response
+type volumeListLibpod struct {
+	// in:body
+	Body []entities.VolumeConfigResponse
+}
+
+// Image Prune
+// swagger:response
+type imagesPruneLibpod struct {
+	// in:body
+	Body []reports.PruneReport
+}
+
+// Remove Containers
+// swagger:response
+type containerRemoveLibpod struct {
+	// in: body
+	Body []handlers.LibpodContainersRmReport
+}
+
+// Prune Containers
+// swagger:response
+type containersPrune struct {
+	// in: body
+	Body []handlers.ContainersPruneReport
+}
+
+// Prune Containers
+// swagger:response
+type containersPruneLibpod struct {
+	// in: body
+	Body []handlers.ContainersPruneReportLibpod
+}
+
+// Get stats for one or more containers
+// swagger:response
+type containerStats struct {
+	// in:body
+	Body define.ContainerStats
+}
+
+// Volume Prune
+// swagger:response
+type volumePruneLibpod struct {
+	// in:body
+	Body []reports.PruneReport
+}
+
+// Create container
+// swagger:response
+type containerCreateResponse struct {
+	// in:body
+	Body entities.ContainerCreateResponse
+}
+
+// Wait container
+// swagger:response
+type containerWaitResponse struct {
+	// in:body
+	Body struct {
+		// container exit code
+		StatusCode int
+		Error      struct {
+			Message string
+		}
+	}
+}
+
+// Network inspect
+// swagger:response
+type networkInspectCompat struct {
+	// in:body
+	Body dockerAPI.NetworkResource
+}
+
+// Network list
+// swagger:response
+type networkListCompat struct {
+	// in:body
+	Body []dockerAPI.NetworkResource
+}
+
+// List Containers
+// swagger:response
+type containersListLibpod struct {
+	// in:body
+	Body []entities.ListContainer
+}
+
+// Inspect Manifest
+// swagger:response
+type manifestInspect struct {
+	// in:body
+	Body manifest.Schema2List
+}
+
+// Kill Pod
+// swagger:response
+type podKillResponse struct {
+	// in:body
+	Body entities.PodKillReport
+}
+
+// Pause pod
+// swagger:response
+type podPauseResponse struct {
+	// in:body
+	Body entities.PodPauseReport
+}
+
+// Unpause pod
+// swagger:response
+type podUnpauseResponse struct {
+	// in:body
+	Body entities.PodUnpauseReport
+}
+
+// Stop pod
+// swagger:response
+type podStopResponse struct {
+	// in:body
+	Body entities.PodStopReport
+}
+
+// Restart pod
+// swagger:response
+type podRestartResponse struct {
+	// in:body
+	Body entities.PodRestartReport
+}
+
+// Start pod
+// swagger:response
+type podStartResponse struct {
+	// in:body
+	Body entities.PodStartReport
+}
+
+// Prune pod
+// swagger:response
+type podPruneResponse struct {
+	// in:body
+	Body entities.PodPruneReport
+}
+
+// Rm pod
+// swagger:response
+type podRmResponse struct {
+	// in:body
+	Body entities.PodRmReport
+}
+
+// Info
+// swagger:response
+type infoResponse struct {
+	// in:body
+	Body define.Info
+}
+
+// Network Delete
+// swagger:response
+type networkRmResponse struct {
+	// in:body
+	Body []entities.NetworkRmReport
+}
+
+// Network inspect
+// swagger:response
+type networkInspectResponse struct {
+	// in:body
+	Body types.Network
+}
+
+// Network list
+// swagger:response
+type networkListLibpod struct {
+	// in:body
+	Body []types.Network
+}
+
+// Network create
+// swagger:model
+type networkCreateLibpod struct {
+	// in:body
+	types.Network
+}
+
+// Network create
+// swagger:response
+type networkCreateResponse struct {
+	// in:body
+	Body types.Network
+}
+
+// Network prune
+// swagger:response
+type networkPruneResponse struct {
+	// in:body
+	Body []entities.NetworkPruneReport
+}
diff --git a/pkg/api/handlers/swagger/swagger.go b/pkg/api/handlers/swagger/swagger.go
deleted file mode 100644
index 7446d901e..000000000
--- a/pkg/api/handlers/swagger/swagger.go
+++ /dev/null
@@ -1,194 +0,0 @@
-package swagger
-
-import (
-	"github.com/containers/podman/v4/libpod/define"
-	"github.com/containers/podman/v4/pkg/api/handlers"
-	"github.com/containers/podman/v4/pkg/domain/entities"
-	"github.com/containers/podman/v4/pkg/inspect"
-	"github.com/docker/docker/api/types"
-)
-
-// Tree response
-// swagger:response TreeResponse
-type swagTree struct {
-	// in:body
-	Body struct {
-		entities.ImageTreeReport
-	}
-}
-
-// History response
-// swagger:response DocsHistory
-type swagHistory struct {
-	// in:body
-	Body struct {
-		handlers.HistoryResponse
-	}
-}
-
-// Inspect response
-// swagger:response DocsImageInspect
-type swagImageInspect struct {
-	// in:body
-	Body struct {
-		handlers.ImageInspect
-	}
-}
-
-// Load response
-// swagger:response DocsLibpodImagesLoadResponse
-type swagLibpodImagesLoadResponse struct {
-	// in:body
-	Body entities.ImageLoadReport
-}
-
-// Import response
-// swagger:response DocsLibpodImagesImportResponse
-type swagLibpodImagesImportResponse struct {
-	// in:body
-	Body entities.ImageImportReport
-}
-
-// Pull response
-// swagger:response DocsLibpodImagesPullResponse
-type swagLibpodImagesPullResponse struct {
-	// in:body
-	Body handlers.LibpodImagesPullReport
-}
-
-// Remove response
-// swagger:response DocsLibpodImagesRemoveResponse
-type swagLibpodImagesRemoveResponse struct {
-	// in:body
-	Body handlers.LibpodImagesRemoveReport
-}
-
-// PlayKube response
-// swagger:response DocsLibpodPlayKubeResponse
-type swagLibpodPlayKubeResponse struct {
-	// in:body
-	Body entities.PlayKubeReport
-}
-
-// Delete response
-// swagger:response DocsImageDeleteResponse
-type swagImageDeleteResponse struct {
-	// in:body
-	Body []struct {
-		Untagged []string `json:"untagged"`
-		Deleted  string   `json:"deleted"`
-	}
-}
-
-// Search results
-// swagger:response DocsSearchResponse
-type swagSearchResponse struct {
-	// in:body
-	Body struct {
-		// Index is the image index (e.g., "docker.io" or "quay.io")
-		Index string
-		// Name is the canonical name of the image (e.g., "docker.io/library/alpine").
-		Name string
-		// Description of the image.
-		Description string
-		// Stars is the number of stars of the image.
-		Stars int
-		// Official indicates if it's an official image.
-		Official string
-		// Automated indicates if the image was created by an automated build.
-		Automated string
-		// Tag is the image tag
-		Tag string
-	}
-}
-
-// Inspect image
-// swagger:response DocsLibpodInspectImageResponse
-type swagLibpodInspectImageResponse struct {
-	// in:body
-	Body struct {
-		inspect.ImageData
-	}
-}
-
-// Rm containers
-// swagger:response DocsLibpodContainerRmReport
-type swagLibpodContainerRmReport struct {
-	// in: body
-	Body []handlers.LibpodContainersRmReport
-}
-
-// Prune containers
-// swagger:response DocsContainerPruneReport
-type swagContainerPruneReport struct {
-	// in: body
-	Body []handlers.ContainersPruneReport
-}
-
-// Prune containers
-// swagger:response DocsLibpodPruneResponse
-type swagLibpodContainerPruneReport struct {
-	// in: body
-	Body []handlers.LibpodContainersPruneReport
-}
-
-// Inspect container
-// swagger:response DocsContainerInspectResponse
-type swagContainerInspectResponse struct {
-	// in:body
-	Body struct {
-		types.ContainerJSON
-	}
-}
-
-// List processes in container
-// swagger:response DocsContainerTopResponse
-type swagContainerTopResponse struct {
-	// in:body
-	Body struct {
-		handlers.ContainerTopOKBody
-	}
-}
-
-// List processes in pod
-// swagger:response DocsPodTopResponse
-type swagPodTopResponse struct {
-	// in:body
-	Body struct {
-		handlers.PodTopOKBody
-	}
-}
-
-// Inspect container
-// swagger:response LibpodInspectContainerResponse
-type swagLibpodInspectContainerResponse struct {
-	// in:body
-	Body struct {
-		define.InspectContainerData
-	}
-}
-
-// List pods
-// swagger:response ListPodsResponse
-type swagListPodsResponse struct {
-	// in:body
-	Body []entities.ListPodsReport
-}
-
-// Inspect pod
-// swagger:response InspectPodResponse
-type swagInspectPodResponse struct {
-	// in:body
-	Body struct {
-		define.InspectPodData
-	}
-}
-
-// Get stats for one or more containers
-// swagger:response ContainerStats
-type swagContainerStatsResponse struct {
-	// in:body
-	Body struct {
-		define.ContainerStats
-	}
-}