From a414460351a82dc10112ae1816cd2d8383d5ca82 Mon Sep 17 00:00:00 2001 From: Tim Zhou Date: Wed, 11 Mar 2026 23:18:04 -0400 Subject: [PATCH] chore(api): add swagger docs for undocumented API parameters Add documentation for undocumented API parameters across multiple endpoints: System: - POST /libpod/system/prune: all, volumes, external, build, filters Pods: - DELETE /libpod/pods/{name}: timeout - GET /libpod/pods/stats: stream, delay Volumes: - DELETE /volumes/{name}: timeout - DELETE /libpod/volumes/{name}: timeout Containers: - GET /libpod/containers/stats: all - POST /libpod/containers/{name}/restart: timeout - POST /libpod/containers/{name}/resize: running Images: - POST /images/create: retry, retryDelay - GET /images/json: shared-size Exec: - POST /libpod/exec/{id}/resize: running Generate: - GET /libpod/generate/{name}/systemd: templateUnitFile Signed-off-by: Tim Zhou --- pkg/api/server/register_containers.go | 15 ++++++++++++++- pkg/api/server/register_exec.go | 4 ++++ pkg/api/server/register_generate.go | 5 +++++ pkg/api/server/register_images.go | 13 +++++++++++++ pkg/api/server/register_pods.go | 16 +++++++++++++++- pkg/api/server/register_system.go | 25 +++++++++++++++++++++++++ pkg/api/server/register_volumes.go | 8 ++++++++ 7 files changed, 84 insertions(+), 2 deletions(-) diff --git a/pkg/api/server/register_containers.go b/pkg/api/server/register_containers.go index 030a2d241f..355c800afa 100644 --- a/pkg/api/server/register_containers.go +++ b/pkg/api/server/register_containers.go @@ -1128,7 +1128,10 @@ func (s *APIServer) registerContainersHandlers(r *mux.Router) error { // - in: query // name: t // type: integer - // default: 10 + // description: number of seconds to wait before killing container (Docker compatibility) + // - in: query + // name: timeout + // type: integer // description: number of seconds to wait before killing container // produces: // - application/json @@ -1220,6 +1223,11 @@ func (s *APIServer) registerContainersHandlers(r *mux.Router) error { // type: integer // default: 5 // description: Time in seconds between stats reports + // - in: query + // name: all + // type: boolean + // default: false + // description: Provide statistics for all running containers // produces: // - application/json // responses: @@ -1560,6 +1568,11 @@ func (s *APIServer) registerContainersHandlers(r *mux.Router) error { // type: integer // required: false // description: Width to set for the terminal, in characters + // - in: query + // name: running + // type: boolean + // required: false + // description: Ignore containers not running errors // produces: // - application/json // responses: diff --git a/pkg/api/server/register_exec.go b/pkg/api/server/register_exec.go index 8f5c6f834b..360981cbf7 100644 --- a/pkg/api/server/register_exec.go +++ b/pkg/api/server/register_exec.go @@ -316,6 +316,10 @@ func (s *APIServer) registerExecHandlers(r *mux.Router) error { // name: w // type: integer // description: Width of the TTY session in characters + // - in: query + // name: running + // type: boolean + // description: Ignore containers not running errors // produces: // - application/json // responses: diff --git a/pkg/api/server/register_generate.go b/pkg/api/server/register_generate.go index d0dcdc1ac5..6bfe8e8bcf 100644 --- a/pkg/api/server/register_generate.go +++ b/pkg/api/server/register_generate.go @@ -102,6 +102,11 @@ func (s *APIServer) registerGenerateHandlers(r *mux.Router) error { // type: string // default: [] // description: Set environment variables to the systemd unit files. + // - in: query + // name: templateUnitFile + // type: boolean + // default: false + // description: Add template specifier for the systemd unit file names. // produces: // - application/json // responses: diff --git a/pkg/api/server/register_images.go b/pkg/api/server/register_images.go index 5802457cd6..a301a7d71e 100644 --- a/pkg/api/server/register_images.go +++ b/pkg/api/server/register_images.go @@ -55,6 +55,14 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // name: platform // type: string // description: Platform in the format os[/arch[/variant]] + // - in: query + // name: retry + // type: integer + // description: Number of times to retry in case of failure when performing pull. + // - in: query + // name: retryDelay + // type: string + // description: Delay between retries in case of pull failures. // - in: body // name: inputImage // schema: @@ -104,6 +112,11 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // description: Not supported // type: boolean // default: false + // - name: shared-size + // in: query + // description: Compute and show shared size as a SharedSize field on each image. + // type: boolean + // default: false // produces: // - application/json // responses: diff --git a/pkg/api/server/register_pods.go b/pkg/api/server/register_pods.go index 51e2c19ee7..af6d3a5b8d 100644 --- a/pkg/api/server/register_pods.go +++ b/pkg/api/server/register_pods.go @@ -93,7 +93,11 @@ func (s *APIServer) registerPodsHandlers(r *mux.Router) error { // - in: query // name: force // type: boolean - // description : force removal of a running pod by first stopping all containers, then removing all containers in the pod + // description: force removal of a running pod by first stopping all containers, then removing all containers in the pod + // - in: query + // name: timeout + // type: integer + // description: number of seconds to wait before killing containers in pod // responses: // 200: // $ref: '#/responses/podRmResponse' @@ -339,6 +343,16 @@ func (s *APIServer) registerPodsHandlers(r *mux.Router) error { // type: array // items: // type: string + // - in: query + // name: stream + // type: boolean + // default: false + // description: Stream the output + // - in: query + // name: delay + // type: integer + // default: 5 + // description: Time in seconds between stats reports // produces: // - application/json // responses: diff --git a/pkg/api/server/register_system.go b/pkg/api/server/register_system.go index b5ee1562a0..c0ba1577c7 100644 --- a/pkg/api/server/register_system.go +++ b/pkg/api/server/register_system.go @@ -65,6 +65,31 @@ func (s *APIServer) registerSystemHandlers(r *mux.Router) error { // tags: // - system // summary: Prune unused data + // parameters: + // - in: query + // name: all + // type: boolean + // description: Remove all unused data, not just dangling data + // - in: query + // name: volumes + // type: boolean + // description: Prune volumes + // - in: query + // name: external + // type: boolean + // description: Remove images used by external containers (e.g., build containers) + // - in: query + // name: build + // type: boolean + // description: Remove build cache + // - in: query + // name: filters + // type: string + // description: | + // JSON encoded value of filters (a map[string][]string) to match data against before pruning. + // Available filters: + // - `until=` Prune data created before this timestamp. The `` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine's time. + // - `label` (`label=`, `label==`, `label!=`, or `label!==`) Prune data with (or without, in case `label!=...` is used) the specified labels. // produces: // - application/json // responses: diff --git a/pkg/api/server/register_volumes.go b/pkg/api/server/register_volumes.go index 65d349a4d1..1fddec9be8 100644 --- a/pkg/api/server/register_volumes.go +++ b/pkg/api/server/register_volumes.go @@ -135,6 +135,10 @@ func (s *APIServer) registerVolumeHandlers(r *mux.Router) error { // name: force // type: boolean // description: force removal + // - in: query + // name: timeout + // type: integer + // description: timeout before forcibly killing any containers using the volume // produces: // - application/json // responses: @@ -299,6 +303,10 @@ func (s *APIServer) registerVolumeHandlers(r *mux.Router) error { // Force removal of the volume. This actually only causes errors due // to the names volume not being found to be suppressed, which is the // behaviour Docker implements. + // - in: query + // name: timeout + // type: integer + // description: timeout before forcibly killing any containers using the volume // produces: // - application/json // responses: