diff options
Diffstat (limited to 'pkg/api/server')
| -rw-r--r-- | pkg/api/server/docs.go | 30 | ||||
| -rw-r--r-- | pkg/api/server/register_containers.go | 845 | ||||
| -rw-r--r-- | pkg/api/server/register_distribution.go | 2 | ||||
| -rw-r--r-- | pkg/api/server/register_events.go | 13 | ||||
| -rw-r--r-- | pkg/api/server/register_healthcheck.go | 2 | ||||
| -rw-r--r-- | pkg/api/server/register_images.go | 463 | ||||
| -rw-r--r-- | pkg/api/server/register_info.go | 8 | ||||
| -rw-r--r-- | pkg/api/server/register_pods.go | 238 | ||||
| -rw-r--r-- | pkg/api/server/register_volumes.go | 32 | ||||
| -rw-r--r-- | pkg/api/server/server.go | 48 | ||||
| -rw-r--r-- | pkg/api/server/swagger.go | 26 |
11 files changed, 918 insertions, 789 deletions
diff --git a/pkg/api/server/docs.go b/pkg/api/server/docs.go new file mode 100644 index 000000000..c989c7927 --- /dev/null +++ b/pkg/api/server/docs.go @@ -0,0 +1,30 @@ +// Package api Provides a container compatible interface. (Experimental) +// +// This documentation describes the HTTP Libpod interface. It is to be considered +// only as experimental as this point. The endpoints, parameters, inputs, and +// return values can all change. +// +// Terms Of Service: +// +// Schemes: http, https +// Host: podman.io +// BasePath: / +// Version: 0.0.1 +// License: Apache-2.0 https://opensource.org/licenses/Apache-2.0 +// Contact: Podman <podman@lists.podman.io> https://podman.io/community/ +// +// InfoExtensions: +// x-logo: +// - url: https://raw.githubusercontent.com/containers/libpod/master/logo/podman-logo.png +// - altText: "Podman logo" +// +// Produces: +// - application/json +// - text/plain +// - text/html +// +// Consumes: +// - application/json +// - application/x-tar +// swagger:meta +package server diff --git a/pkg/api/server/register_containers.go b/pkg/api/server/register_containers.go index 833bb5197..abae81c38 100644 --- a/pkg/api/server/register_containers.go +++ b/pkg/api/server/register_containers.go @@ -23,25 +23,39 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // type: string // description: container name // responses: - // '201': - // $ref: "#/responses/ContainerCreateResponse" - // '400': - // "$ref": "#/responses/BadParamError" - // '404': - // "$ref": "#/responses/NoSuchContainer" - // '409': - // "$ref": "#/responses/ConflictError" - // '500': - // "$ref": "#/responses/InternalError" - r.HandleFunc(VersionedPath("/containers/create"), APIHandler(s.Context, generic.CreateContainer)).Methods(http.MethodPost) + // 201: + // $ref: "#/responses/ContainerCreateResponse" + // 400: + // $ref: "#/responses/BadParamError" + // 404: + // $ref: "#/responses/NoSuchContainer" + // 409: + // $ref: "#/responses/ConflictError" + // 500: + // $ref: "#/responses/InternalError" + r.HandleFunc(VersionedPath("/containers/create"), APIHandler(s.Context, handlers.CreateContainer)).Methods(http.MethodPost) // swagger:operation GET /containers/json compat listContainers // --- - // tags: - // - containers (compat) + // tags: + // - containers (compat) // summary: List containers // description: Returns a list of containers // parameters: // - in: query + // name: all + // type: boolean + // default: false + // description: Return all containers. By default, only running containers are shown + // - in: query + // name: limit + // description: Return this number of most recently created containers, including non-running ones. + // type: integer + // - in: query + // name: size + // type: boolean + // default: false + // description: Return the size of container as fields SizeRw and SizeRootFs. + // - in: query // name: filters // type: string // description: | @@ -63,17 +77,17 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // produces: // - application/json // responses: - // '200': - // "$ref": "#/responses/DocsListContainer" - // '400': - // "$ref": "#/responses/BadParamError" - // '500': - // "$ref": "#/responses/InternalError" + // 200: + // $ref: "#/responses/DocsListContainer" + // 400: + // $ref: "#/responses/BadParamError" + // 500: + // $ref: "#/responses/InternalError" r.HandleFunc(VersionedPath("/containers/json"), APIHandler(s.Context, generic.ListContainers)).Methods(http.MethodGet) // swagger:operation POST /containers/prune compat pruneContainers // --- - // tags: - // - containers (compat) + // tags: + // - containers (compat) // summary: Delete stopped containers // description: Remove containers not in use // parameters: @@ -87,76 +101,78 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // produces: // - application/json // responses: - // '200': - // "$ref": "#/responses/DocsContainerPruneReport" - // '500': - // "$ref": "#/responses/InternalError" - r.HandleFunc(VersionedPath("/containers/prune"), APIHandler(s.Context, generic.PruneContainers)).Methods(http.MethodPost) - // swagger:operation DELETE /containers/{nameOrID} compat removeContainer + // 200: + // $ref: "#/responses/DocsContainerPruneReport" + // 500: + // $ref: "#/responses/InternalError" + r.HandleFunc(VersionedPath("/containers/prune"), APIHandler(s.Context, handlers.PruneContainers)).Methods(http.MethodPost) + // swagger:operation DELETE /containers/{name} compat removeContainer // --- - // tags: - // - containers (compat) + // tags: + // - containers (compat) // summary: Remove a container // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container // - in: query // name: force - // type: bool + // type: boolean // default: false // description: If the container is running, kill it before removing it. // - in: query // name: v - // type: bool + // type: boolean // default: false // description: Remove the volumes associated with the container. // - in: query // name: link - // type: bool + // type: boolean // description: not supported // produces: // - application/json // responses: - // '204': + // 204: // description: no error - // '400': - // "$ref": "#/responses/BadParamError" - // '404': - // "$ref": "#/responses/NoSuchContainer" - // '409': - // "$ref": "#/responses/ConflictError" - // '500': - // "$ref": "#/responses/InternalError" - r.HandleFunc(VersionedPath("/containers/{name:..*}"), APIHandler(s.Context, generic.RemoveContainer)).Methods(http.MethodDelete) - // swagger:operation GET /containers/{nameOrID}/json compat getContainer + // 400: + // $ref: "#/responses/BadParamError" + // 404: + // $ref: "#/responses/NoSuchContainer" + // 409: + // $ref: "#/responses/ConflictError" + // 500: + // $ref: "#/responses/InternalError" + r.HandleFunc(VersionedPath("/containers/{name}"), APIHandler(s.Context, generic.RemoveContainer)).Methods(http.MethodDelete) + // swagger:operation GET /containers/{name}/json compat getContainer // --- - // tags: - // - containers (compat) + // tags: + // - containers (compat) // summary: Inspect container // description: Return low-level information about a container. // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or id of the container // - in: query // name: size - // type: bool + // type: boolean // default: false // description: include the size of the container // produces: // - application/json // responses: - // '200': - // "$ref": "#/responses/DocsContainerInspectResponse" - // '404': - // "$ref": "#/responses/NoSuchContainer" - // '500': - // "$ref": "#/responses/InternalError" - r.HandleFunc(VersionedPath("/containers/{name:..*}/json"), APIHandler(s.Context, generic.GetContainer)).Methods(http.MethodGet) - // swagger:operation post /containers/{nameOrID}/kill compat killcontainer + // 200: + // $ref: "#/responses/DocsContainerInspectResponse" + // 404: + // $ref: "#/responses/NoSuchContainer" + // 500: + // $ref: "#/responses/InternalError" + r.HandleFunc(VersionedPath("/containers/{name}/json"), APIHandler(s.Context, generic.GetContainer)).Methods(http.MethodGet) + // swagger:operation post /containers/{name}/kill compat killcontainer // --- // tags: // - containers (compat) @@ -164,26 +180,29 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // description: Signal to send to the container as an integer or string (e.g. SIGINT) // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container // - in: query // name: signal - // type: int + // type: string + // default: TERM // description: signal to be sent to container + // default: SIGKILL // produces: // - application/json // responses: - // '204': + // 204: // description: no error - // '404': - // "$ref": "#/responses/NoSuchContainer" - // '409': - // "$ref": "#/responses/ConflictError" - // '500': - // "$ref": "#/responses/InternalError" - r.HandleFunc(VersionedPath("/containers/{name:..*}/kill"), APIHandler(s.Context, generic.KillContainer)).Methods(http.MethodPost) - // swagger:operation GET /containers/{nameOrID}/logs compat LogsFromContainer + // 404: + // $ref: "#/responses/NoSuchContainer" + // 409: + // $ref: "#/responses/ConflictError" + // 500: + // $ref: "#/responses/InternalError" + r.HandleFunc(VersionedPath("/containers/{name}/kill"), APIHandler(s.Context, generic.KillContainer)).Methods(http.MethodPost) + // swagger:operation GET /containers/{name}/logs compat LogsFromContainer // --- // tags: // - containers (compat) @@ -191,20 +210,21 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // description: Get stdout and stderr logs from a container. // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container // - in: query // name: follow - // type: bool + // type: boolean // description: Keep connection after returning logs. // - in: query // name: stdout - // type: bool + // type: boolean // description: not supported // - in: query // name: stderr - // type: bool + // type: boolean // description: not supported? // - in: query // name: since @@ -216,7 +236,7 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // description: Only return logs before this time, as a UNIX timestamp // - in: query // name: timestamps - // type: bool + // type: boolean // default: false // description: Add timestamps to every log line // - in: query @@ -227,14 +247,14 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // produces: // - application/json // responses: - // '200': + // 200: // description: logs returned as a stream in response body. - // '404': - // "$ref": "#/responses/NoSuchContainer" - // '500': - // "$ref": "#/responses/InternalError" - r.HandleFunc(VersionedPath("/containers/{name:..*}/logs"), APIHandler(s.Context, generic.LogsFromContainer)).Methods(http.MethodGet) - // swagger:operation POST /containers/{nameOrID}/pause compat pauseContainer + // 404: + // $ref: "#/responses/NoSuchContainer" + // 500: + // $ref: "#/responses/InternalError" + r.HandleFunc(VersionedPath("/containers/{name}/logs"), APIHandler(s.Context, generic.LogsFromContainer)).Methods(http.MethodGet) + // swagger:operation POST /containers/{name}/pause compat pauseContainer // --- // tags: // - containers (compat) @@ -242,71 +262,75 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // description: Use the cgroups freezer to suspend all processes in a container. // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container // produces: // - application/json // responses: - // '204': + // 204: // description: no error - // '404': - // "$ref": "#/responses/NoSuchContainer" - // '500': - // "$ref": "#/responses/InternalError" - r.HandleFunc(VersionedPath("/containers/{name:..*}/pause"), APIHandler(s.Context, handlers.PauseContainer)).Methods(http.MethodPost) - r.HandleFunc(VersionedPath("/containers/{name:..*}/rename"), APIHandler(s.Context, handlers.UnsupportedHandler)).Methods(http.MethodPost) - // swagger:operation POST /containers/{nameOrID}/restart compat restartContainer + // 404: + // $ref: "#/responses/NoSuchContainer" + // 500: + // $ref: "#/responses/InternalError" + r.HandleFunc(VersionedPath("/containers/{name}/pause"), APIHandler(s.Context, handlers.PauseContainer)).Methods(http.MethodPost) + r.HandleFunc(VersionedPath("/containers/{name}/rename"), APIHandler(s.Context, handlers.UnsupportedHandler)).Methods(http.MethodPost) + // swagger:operation POST /containers/{name}/restart compat restartContainer // --- // tags: // - containers (compat) // summary: Restart container // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container // - in: query // name: t - // type: int + // type: integer // description: timeout before sending kill signal to container // produces: // - application/json // responses: - // '204': + // 204: // description: no error - // '404': - // "$ref": "#/responses/NoSuchContainer" - // '500': - // "$ref": "#/responses/InternalError" - r.HandleFunc(VersionedPath("/containers/{name:..*}/restart"), APIHandler(s.Context, handlers.RestartContainer)).Methods(http.MethodPost) - // swagger:operation POST /containers/{nameOrID}/start compat startContainer + // 404: + // $ref: "#/responses/NoSuchContainer" + // 500: + // $ref: "#/responses/InternalError" + r.HandleFunc(VersionedPath("/containers/{name}/restart"), APIHandler(s.Context, handlers.RestartContainer)).Methods(http.MethodPost) + // swagger:operation POST /containers/{name}/start compat startContainer // --- // tags: // - containers (compat) // summary: Start a container // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container // - in: query // name: detachKeys // type: string - // description: needs description + // description: "Override the key sequence for detaching a container. Format is a single character [a-Z] or ctrl-<value> where <value> is one of: a-z, @, ^, [, , or _." + // default: ctrl-p,ctrl-q // produces: // - application/json // responses: - // '204': + // 204: // description: no error - // '304': - // "$ref": "#/responses/ContainerAlreadyStartedError" - // '404': - // "$ref": "#/responses/NoSuchContainer" - // '500': - // "$ref": "#/responses/InternalError" - r.HandleFunc(VersionedPath("/containers/{name:..*}/start"), APIHandler(s.Context, handlers.StartContainer)).Methods(http.MethodPost) - // swagger:operation GET /containers/{nameOrID}/stats compat statsContainer + // 304: + // $ref: "#/responses/ContainerAlreadyStartedError" + // 404: + // $ref: "#/responses/NoSuchContainer" + // 500: + // $ref: "#/responses/InternalError" + r.HandleFunc(VersionedPath("/containers/{name}/start"), APIHandler(s.Context, handlers.StartContainer)).Methods(http.MethodPost) + // swagger:operation GET /containers/{name}/stats compat statsContainer // --- // tags: // - containers (compat) @@ -314,58 +338,62 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // description: This returns a live stream of a container’s resource usage statistics. // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container // - in: query // name: stream - // type: bool + // type: boolean // default: true // description: Stream the output // produces: // - application/json // responses: - // '200': - // description: no error - // '404': - // "$ref": "#/responses/NoSuchContainer" - // '500': - // "$ref": "#/responses/InternalError" - r.HandleFunc(VersionedPath("/containers/{name:..*}/stats"), APIHandler(s.Context, generic.StatsContainer)).Methods(http.MethodGet) - // swagger:operation POST /containers/{nameOrID}/stop compat stopContainer + // 200: + // description: OK + // 404: + // $ref: "#/responses/NoSuchContainer" + // 500: + // $ref: "#/responses/InternalError" + r.HandleFunc(VersionedPath("/containers/{name}/stats"), APIHandler(s.Context, generic.StatsContainer)).Methods(http.MethodGet) + // swagger:operation POST /containers/{name}/stop compat stopContainer // --- // tags: // - containers (compat) // summary: Stop a container + // description: Stop a container // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container // - in: query // name: t - // type: int + // type: integer // description: number of seconds to wait before killing container // produces: // - application/json // responses: - // '204': + // 204: // description: no error - // '304': - // "$ref": "#/responses/ContainerAlreadyStoppedError" - // '404': - // "$ref": "#/responses/NoSuchContainer" - // '500': - // "$ref": "#/responses/InternalError" - r.HandleFunc(VersionedPath("/containers/{name:..*}/stop"), APIHandler(s.Context, handlers.StopContainer)).Methods(http.MethodPost) - // swagger:operation GET /containers/{nameOrID}/top compat topContainer + // 304: + // $ref: "#/responses/ContainerAlreadyStoppedError" + // 404: + // $ref: "#/responses/NoSuchContainer" + // 500: + // $ref: "#/responses/InternalError" + r.HandleFunc(VersionedPath("/containers/{name}/stop"), APIHandler(s.Context, handlers.StopContainer)).Methods(http.MethodPost) + // swagger:operation GET /containers/{name}/top compat topContainer // --- // tags: // - containers (compat) // summary: List processes running inside a container // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container // - in: query @@ -375,14 +403,14 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // produces: // - application/json // responses: - // '200': - // "ref": "#/responses/DockerTopResponse" - // '404': - // "$ref": "#/responses/NoSuchContainer" - // '500': - // "$ref": "#/responses/InternalError" - r.HandleFunc(VersionedPath("/containers/{name:..*}/top"), APIHandler(s.Context, handlers.TopContainer)).Methods(http.MethodGet) - // swagger:operation POST /containers/{nameOrID}/unpause compat unpauseContainer + // 200: + // $ref: "#/responses/DockerTopResponse" + // 404: + // $ref: "#/responses/NoSuchContainer" + // 500: + // $ref: "#/responses/InternalError" + r.HandleFunc(VersionedPath("/containers/{name}/top"), APIHandler(s.Context, handlers.TopContainer)).Methods(http.MethodGet) + // swagger:operation POST /containers/{name}/unpause compat unpauseContainer // --- // tags: // - containers (compat) @@ -390,20 +418,21 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // description: Resume a paused container // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container // produces: // - application/json // responses: - // '204': + // 204: // description: no error - // '404': - // "$ref": "#/responses/NoSuchContainer" - // '500': - // "$ref": "#/responses/InternalError" - r.HandleFunc(VersionedPath("/containers/{name:..*}/unpause"), APIHandler(s.Context, handlers.UnpauseContainer)).Methods(http.MethodPost) - // swagger:operation POST /containers/{nameOrID}/wait compat waitContainer + // 404: + // $ref: "#/responses/NoSuchContainer" + // 500: + // $ref: "#/responses/InternalError" + r.HandleFunc(VersionedPath("/containers/{name}/unpause"), APIHandler(s.Context, handlers.UnpauseContainer)).Methods(http.MethodPost) + // swagger:operation POST /containers/{name}/wait compat waitContainer // --- // tags: // - containers (compat) @@ -411,24 +440,25 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // description: Block until a container stops, then returns the exit code. // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container // - in: query // name: condition // type: string - // description: Wait until the container reaches the given condition + // description: not supported // produces: // - application/json // responses: - // '200': + // 200: // $ref: "#/responses/ContainerWaitResponse" - // '404': - // "$ref": "#/responses/NoSuchContainer" - // '500': - // "$ref": "#/responses/InternalError" - r.HandleFunc(VersionedPath("/containers/{name:..*}/wait"), APIHandler(s.Context, generic.WaitContainer)).Methods(http.MethodPost) - // swagger:operation POST /containers/{nameOrID}/attach compat attach + // 404: + // $ref: "#/responses/NoSuchContainer" + // 500: + // $ref: "#/responses/InternalError" + r.HandleFunc(VersionedPath("/containers/{name}/wait"), APIHandler(s.Context, generic.WaitContainer)).Methods(http.MethodPost) + // swagger:operation POST /containers/{name}/attach compat attach // --- // tags: // - containers (compat) @@ -436,7 +466,8 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // description: Hijacks the connection to forward the container's standard streams to the client. // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container // - in: query @@ -447,42 +478,42 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // - in: query // name: logs // required: false - // type: bool + // type: boolean // description: Not yet supported // - in: query // name: stream // required: false - // type: bool + // type: boolean // default: true // description: If passed, must be set to true; stream=false is not yet supported // - in: query // name: stdout // required: false - // type: bool + // type: boolean // description: Attach to container STDOUT // - in: query // name: stderr // required: false - // type: bool + // type: boolean // description: Attach to container STDERR // - in: query // name: stdin // required: false - // type: bool + // type: boolean // description: Attach to container STDIN // produces: // - application/json // responses: - // '101': + // 101: // description: No error, connection has been hijacked for transporting streams. - // '400': - // "$ref": "#/responses/BadParamError" - // '404': - // "$ref": "#/responses/NoSuchContainer" - // '500': - // "$ref": "#/responses/InternalError" - r.HandleFunc(VersionedPath("/containers/{name:..*}/attach"), APIHandler(s.Context, handlers.AttachContainer)).Methods(http.MethodPost) - // swagger:operation POST /containers/{nameOrID}/resize compat resize + // 400: + // $ref: "#/responses/BadParamError" + // 404: + // $ref: "#/responses/NoSuchContainer" + // 500: + // $ref: "#/responses/InternalError" + r.HandleFunc(VersionedPath("/containers/{name}/attach"), APIHandler(s.Context, handlers.AttachContainer)).Methods(http.MethodPost) + // swagger:operation POST /containers/{name}/resize compat resize // --- // tags: // - containers (compat) @@ -490,64 +521,109 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // description: Resize the terminal attached to a container (for use with Attach). // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container // - in: query // name: h - // type: int + // type: integer // required: false // description: Height to set for the terminal, in characters // - in: query // name: w - // type: int + // type: integer // required: false // description: Width to set for the terminal, in characters // produces: // - application/json // responses: - // '200': - // description: no error - // '404': - // "$ref": "#/responses/NoSuchContainer" - // '500': - // "$ref": "#/responses/InternalError" - r.HandleFunc(VersionedPath("/containers/{name:..*}/resize"), APIHandler(s.Context, handlers.ResizeContainer)).Methods(http.MethodPost) + // 200: + // $ref: "#/responses/ok" + // 404: + // $ref: "#/responses/NoSuchContainer" + // 500: + // $ref: "#/responses/InternalError" + r.HandleFunc(VersionedPath("/containers/{name}/resize"), APIHandler(s.Context, handlers.ResizeContainer)).Methods(http.MethodPost) /* libpod endpoints */ - r.HandleFunc(VersionedPath("/libpod/containers/create"), APIHandler(s.Context, libpod.CreateContainer)).Methods(http.MethodPost) + r.HandleFunc(VersionedPath("/libpod/containers/create"), APIHandler(s.Context, handlers.CreateContainer)).Methods(http.MethodPost) // swagger:operation GET /libpod/containers/json libpod libpodListContainers // --- // tags: // - containers // summary: List containers // description: Returns a list of containers + // parameters: + // - in: query + // name: all + // type: boolean + // default: false + // description: Return all containers. By default, only running containers are shown + // - in: query + // name: limit + // description: Return this number of most recently created containers, including non-running ones. + // type: integer + // - in: query + // name: namespace + // type: boolean + // description: Include namespace information + // default: false + // - in: query + // name: pod + // type: boolean + // default: false + // description: Include Pod ID and Name if applicable + // - in: query + // name: size + // type: boolean + // default: false + // description: Return the size of container as fields SizeRw and SizeRootFs. + // - in: query + // name: sync + // type: boolean + // default: false + // description: Sync container state with OCI runtime + // - in: query + // name: filters + // type: string + // description: | + // Returns a list of containers. + // - ancestor=(<image-name>[:<tag>], <image id>, or <image@digest>) + // - before=(<container id> or <container name>) + // - expose=(<port>[/<proto>]|<startport-endport>/[<proto>]) + // - exited=<int> containers with exit code of <int> + // - health=(starting|healthy|unhealthy|none) + // - id=<ID> a container's ID + // - is-task=(true|false) + // - label=key or label="key=value" of a container label + // - name=<name> a container's name + // - network=(<network id> or <network name>) + // - publish=(<port>[/<proto>]|<startport-endport>/[<proto>]) + // - since=(<container id> or <container name>) + // - status=(created|restarting|running|removing|paused|exited|dead) + // - volume=(<volume name> or <mount point destination>) // produces: // - application/json // responses: - // '200': - // schema: - // "$ref": "#/responses/LibpodListContainersResponse" - // '400': - // "$ref": "#/responses/BadParamError" - // '500': - // "$ref": "#/responses/InternalError" + // 200: + // $ref: "#/responses/LibpodListContainersResponse" + // 400: + // $ref: "#/responses/BadParamError" + // 500: + // $ref: "#/responses/InternalError" r.HandleFunc(VersionedPath("/libpod/containers/json"), APIHandler(s.Context, libpod.ListContainers)).Methods(http.MethodGet) - // swagger:operation POST /libpod/containers/prune libpod libpodPruneContainers + // swagger:operation POST /libpod/containers/prune libpod libpodPruneContainers // --- // tags: - // - containers - // summary: Prune unused containers - // description: Remove stopped and exited containers + // - containers + // summary: Delete stopped containers + // description: Remove containers not in use // parameters: // - in: query - // name: force - // type: bool - // description: something - // - in: query // name: filters // type: string // description: | @@ -557,11 +633,11 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // produces: // - application/json // responses: - // '200': - // description: to be determined - // '500': - // "$ref": "#/responses/InternalError" - r.HandleFunc(VersionedPath("/libpod/containers/prune"), APIHandler(s.Context, libpod.PruneContainers)).Methods(http.MethodPost) + // 200: + // $ref: "#/responses/DocsLibpodPruneResponse" + // 500: + // $ref: "#/responses/InternalError" + r.HandleFunc(VersionedPath("/libpod/containers/prune"), APIHandler(s.Context, handlers.PruneContainers)).Methods(http.MethodPost) // swagger:operation GET /libpod/containers/showmounted libpod showMounterContainers // --- // tags: @@ -571,48 +647,50 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // produces: // - application/json // responses: - // '200': + // 200: // description: mounted containers // schema: // type: object // additionalProperties: // type: string - // '500': - // "$ref": "#/responses/InternalError" + // 500: + // $ref: "#/responses/InternalError" r.HandleFunc(VersionedPath("/libpod/containers/showmounted"), APIHandler(s.Context, libpod.ShowMountedContainers)).Methods(http.MethodGet) - // swagger:operation DELETE /libpod/containers/json libpod libpodRemoveContainer + // swagger:operation DELETE /libpod/containers/{name} libpod libpodRemoveContainer // --- // tags: // - containers // summary: Delete container + // description: Delete container // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container // - in: query // name: force - // type: bool + // type: boolean // description: need something // - in: query // name: v - // type: bool + // type: boolean // description: delete volumes // produces: // - application/json // responses: - // '204': + // 204: // description: no error - // '400': - // "$ref": "#/responses/BadParamError" - // '404': - // "$ref": "#/responses/NoSuchContainer" - // '409': - // "$ref": "#/responses/ConflictError" - // '500': - // "$ref": "#/responses/InternalError" - r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}"), APIHandler(s.Context, libpod.RemoveContainer)).Methods(http.MethodDelete) - // swagger:operation GET /libpod/containers/{nameOrID}/json libpod libpodGetContainer + // 400: + // $ref: "#/responses/BadParamError" + // 404: + // $ref: "#/responses/NoSuchContainer" + // 409: + // $ref: "#/responses/ConflictError" + // 500: + // $ref: "#/responses/InternalError" + r.HandleFunc(VersionedPath("/libpod/containers/{name}"), APIHandler(s.Context, libpod.RemoveContainer)).Methods(http.MethodDelete) + // swagger:operation GET /libpod/containers/{name}/json libpod libpodGetContainer // --- // tags: // - containers @@ -620,24 +698,25 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // description: Return low-level information about a container. // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container // - in: query // name: size - // type: bool + // type: boolean // description: display filesystem usage // produces: // - application/json // responses: - // '200': - // "$ref": "#/responses/LibpodInspectContainerResponse" - // '404': - // "$ref": "#/responses/NoSuchContainer" - // '500': - // "$ref": "#/responses/InternalError" - r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/json"), APIHandler(s.Context, libpod.GetContainer)).Methods(http.MethodGet) - // swagger:operation POST /libpod/containers/{nameOrID}/kill libpod libpodKillContainer + // 200: + // $ref: "#/responses/LibpodInspectContainerResponse" + // 404: + // $ref: "#/responses/NoSuchContainer" + // 500: + // $ref: "#/responses/InternalError" + r.HandleFunc(VersionedPath("/libpod/containers/{name}/json"), APIHandler(s.Context, libpod.GetContainer)).Methods(http.MethodGet) + // swagger:operation POST /libpod/containers/{name}/kill libpod libpodKillContainer // --- // tags: // - containers @@ -645,27 +724,28 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // description: send a signal to a container, defaults to killing the container // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container // - in: query // name: signal - // type: int - // default: 15 - // description: signal to be sent to container + // type: string + // default: TERM + // description: signal to be sent to container, either by integer or SIG_ name // produces: // - application/json // responses: - // '204': + // 204: // description: no error - // '404': - // "$ref": "#/responses/NoSuchContainer" - // '409': - // "$ref": "#/responses/ConflictError" - // '500': - // "$ref": "#/responses/InternalError" - r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/kill"), APIHandler(s.Context, libpod.KillContainer)).Methods(http.MethodGet) - // swagger:operation POST /libpod/containers/{nameOrID}/mount libpod mountContainer + // 404: + // $ref: "#/responses/NoSuchContainer" + // 409: + // $ref: "#/responses/ConflictError" + // 500: + // $ref: "#/responses/InternalError" + r.HandleFunc(VersionedPath("/libpod/containers/{name}/kill"), APIHandler(s.Context, libpod.KillContainer)).Methods(http.MethodGet) + // swagger:operation GET /libpod/containers/{name}/mount libpod mountContainer // --- // tags: // - containers @@ -673,46 +753,48 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // description: Mount a container to the filesystem // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container // produces: // - application/json // responses: - // '200': + // 200: // description: mounted container // schema: // description: id // type: string // example: /var/lib/containers/storage/overlay/f3f693bd88872a1e3193f4ebb925f4c282e8e73aadb8ab3e7492754dda3a02a4/merged - // '404': - // "$ref": "#/responses/NoSuchContainer" - // '500': - // "$ref": "#/responses/InternalError" - r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/mount"), APIHandler(s.Context, libpod.MountContainer)).Methods(http.MethodPost) - // swagger:operation GET /libpod/containers/{nameOrID}/unmount libpod unmountContainer + // 404: + // $ref: "#/responses/NoSuchContainer" + // 500: + // $ref: "#/responses/InternalError" + r.HandleFunc(VersionedPath("/libpod/containers/{name}/mount"), APIHandler(s.Context, libpod.MountContainer)).Methods(http.MethodPost) + // swagger:operation POST /libpod/containers/{name}/unmount libpod libpodUnmountContainer // --- // tags: // - containers // summary: Unmount a container // description: Unmount a container from the filesystem + // produces: + // - application/json // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container - // produces: - // - application/json // responses: - // '204': - // description: no error - // '404': - // "$ref": "#/responses/NoSuchContainer" - // '500': - // "$ref": "#/responses/InternalError" - r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/unmount"), APIHandler(s.Context, libpod.UnmountContainer)).Methods(http.MethodPost) - r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/logs"), APIHandler(s.Context, libpod.LogsFromContainer)).Methods(http.MethodGet) - // swagger:operation POST /libpod/containers/{nameOrID}/pause libpod libpodPauseContainer + // 204: + // description: ok + // 404: + // $ref: "#/responses/NoSuchContainer" + // 500: + // $ref: "#/responses/InternalError" + r.HandleFunc(VersionedPath("/libpod/containers/{name}/unmount"), APIHandler(s.Context, libpod.UnmountContainer)).Methods(http.MethodPost) + r.HandleFunc(VersionedPath("/libpod/containers/{name}/logs"), APIHandler(s.Context, libpod.LogsFromContainer)).Methods(http.MethodGet) + // swagger:operation POST /libpod/containers/{name}/pause libpod libpodPauseContainer // --- // tags: // - containers @@ -720,70 +802,74 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // description: Use the cgroups freezer to suspend all processes in a container. // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container // produces: // - application/json // responses: - // '204': + // 204: // description: no error - // '404': - // "$ref": "#/responses/NoSuchContainer" - // '500': - // "$ref": "#/responses/InternalError" + // 404: + // "$ref": "#/responses/NoSuchContainer" + // 500: + // "$ref": "#/responses/InternalError" r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/pause"), APIHandler(s.Context, handlers.PauseContainer)).Methods(http.MethodPost) - // swagger:operation POST /libpod/containers/{nameOrID}/restart libpod libpodRestartContainer + // swagger:operation POST /libpod/containers/{name}/restart libpod libpodRestartContainer // --- // tags: // - containers // summary: Restart a container // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container // - in: query // name: t - // type: int + // type: integer // description: timeout before sending kill signal to container // produces: // - application/json // responses: - // '204': + // 204: // description: no error - // '404': - // "$ref": "#/responses/NoSuchContainer" - // '500': - // "$ref": "#/responses/InternalError" - r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/restart"), APIHandler(s.Context, handlers.RestartContainer)).Methods(http.MethodPost) - // swagger:operation POST /libpod/containers/{nameOrID}/start libpod libpodStartContainer + // 404: + // $ref: "#/responses/NoSuchContainer" + // 500: + // $ref: "#/responses/InternalError" + r.HandleFunc(VersionedPath("/libpod/containers/{name}/restart"), APIHandler(s.Context, handlers.RestartContainer)).Methods(http.MethodPost) + // swagger:operation POST /libpod/containers/{name}/start libpod libpodStartContainer // --- // tags: // - containers // summary: Start a container // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container // - in: query // name: detachKeys // type: string - // description: needs description + // description: "Override the key sequence for detaching a container. Format is a single character [a-Z] or ctrl-<value> where <value> is one of: a-z, @, ^, [, , or _." + // default: ctrl-p,ctrl-q // produces: // - application/json // responses: - // '204': + // 204: // description: no error - // '304': - // "$ref": "#/responses/ContainerAlreadyStartedError" - // '404': - // "$ref": "#/responses/NoSuchContainer" - // '500': - // "$ref": "#/responses/InternalError" - r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/start"), APIHandler(s.Context, handlers.StartContainer)).Methods(http.MethodPost) - // swagger:operation GET /libpod/containers/{nameOrID}/stats libpod statsContainer + // 304: + // $ref: "#/responses/ContainerAlreadyStartedError" + // 404: + // $ref: "#/responses/NoSuchContainer" + // 500: + // $ref: "#/responses/InternalError" + r.HandleFunc(VersionedPath("/libpod/containers/{name}/start"), APIHandler(s.Context, handlers.StartContainer)).Methods(http.MethodPost) + // swagger:operation GET /libpod/containers/{name}/stats libpod libpodStatsContainer // --- // tags: // - containers @@ -791,99 +877,102 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // description: This returns a live stream of a container’s resource usage statistics. // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container // - in: query // name: stream - // type: bool + // type: boolean // default: true // description: Stream the output // produces: // - application/json // responses: - // '200': + // 200: // description: no error - // '404': - // "$ref": "#/responses/NoSuchContainer" - // '500': - // "$ref": "#/responses/InternalError" - r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/stats"), APIHandler(s.Context, generic.StatsContainer)).Methods(http.MethodGet) - // swagger:operation GET /libpod/containers/{nameOrID}/top libpod libpodTopContainer - // - // List processes running inside a container. Note - // + // 404: + // $ref: "#/responses/NoSuchContainer" + // 500: + // $ref: "#/responses/InternalError" + r.HandleFunc(VersionedPath("/libpod/containers/{name}/stats"), APIHandler(s.Context, generic.StatsContainer)).Methods(http.MethodGet) + // swagger:operation GET /libpod/containers/{name}/top libpod libpodTopContainer // --- // tags: // - containers + // summary: List processes + // description: List processes running inside a container // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true - // description: the name or ID of the container + // description: | + // Name of container to query for processes + // (As of version 1.xx) // - in: query // name: stream - // type: bool + // type: boolean // default: true // description: Stream the output + // - in: query // name: ps_args // type: string + // default: -ef // description: arguments to pass to ps such as aux. Requires ps(1) to be installed in the container if no ps(1) compatible AIX descriptors are used. // produces: // - application/json // responses: - // '200': - // "ref": "#/responses/DockerTopResponse" - // '404': - // "$ref": "#/responses/NoSuchContainer" - // '500': - // "$ref": "#/responses/InternalError" - r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/top"), APIHandler(s.Context, handlers.TopContainer)).Methods(http.MethodGet) - // swagger:operation POST /libpod/containers/{nameOrID}/unpause libpod libpodUnpauseContainer + // 200: + // $ref: "#/responses/DockerTopResponse" + // 404: + // $ref: "#/responses/NoSuchContainer" + // 500: + // $ref: "#/responses/InternalError" + r.HandleFunc(VersionedPath("/libpod/containers/{name}/top"), APIHandler(s.Context, handlers.TopContainer)).Methods(http.MethodGet) + // swagger:operation POST /libpod/containers/{name}/unpause libpod libpodUnpauseContainer // --- // tags: // - containers // summary: Unpause Container // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container // produces: // - application/json // responses: - // '204': + // 204: // description: no error - // '404': - // "$ref": "#/responses/NoSuchContainer" - // '500': - // "$ref": "#/responses/InternalError" - r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/unpause"), APIHandler(s.Context, handlers.UnpauseContainer)).Methods(http.MethodPost) - // swagger:operation POST /libpod/containers/{nameOrID}/wait libpod libpodWaitContainer + // 404: + // $ref: "#/responses/NoSuchContainer" + // 500: + // $ref: "#/responses/InternalError" + r.HandleFunc(VersionedPath("/libpod/containers/{name}/unpause"), APIHandler(s.Context, handlers.UnpauseContainer)).Methods(http.MethodPost) + // swagger:operation POST /libpod/containers/{name}/wait libpod libpodWaitContainer // --- // tags: // - containers // summary: Wait on a container to exit // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container - // - in: query - // name: condition - // type: string - // description: Wait until the container reaches the given condition // produces: // - application/json // responses: - // '204': + // 204: // description: no error - // '404': - // "$ref": "#/responses/NoSuchContainer" - // '500': - // "$ref": "#/responses/InternalError" - r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/wait"), APIHandler(s.Context, libpod.WaitContainer)).Methods(http.MethodPost) - // swagger:operation POST /libpod/containers/{nameOrID}/exists libpod containerExists + // 404: + // $ref: "#/responses/NoSuchContainer" + // 500: + // $ref: "#/responses/InternalError" + r.HandleFunc(VersionedPath("/libpod/containers/{name}/wait"), APIHandler(s.Context, libpod.WaitContainer)).Methods(http.MethodPost) + // swagger:operation POST /libpod/containers/{name}/exists libpod containerExists // --- // tags: // - containers @@ -891,46 +980,48 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // description: Quick way to determine if a container exists by name or ID // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container // produces: // - application/json // responses: - // '204': + // 204: // description: container exists - // '404': - // "$ref": "#/responses/NoSuchContainer" - // '500': - // "$ref": "#/responses/InternalError" - r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/exists"), APIHandler(s.Context, libpod.ContainerExists)).Methods(http.MethodGet) - // swagger:operation POST /libpod/containers/{nameOrID}/stop libpod libpodStopContainer + // 404: + // $ref: "#/responses/NoSuchContainer" + // 500: + // $ref: "#/responses/InternalError" + r.HandleFunc(VersionedPath("/libpod/containers/{name}/exists"), APIHandler(s.Context, libpod.ContainerExists)).Methods(http.MethodGet) + // swagger:operation POST /libpod/containers/{name}/stop libpod libpodStopContainer // --- // tags: // - containers // summary: Stop a container // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container // - in: query // name: t - // type: int + // type: integer // description: number of seconds to wait before killing container // produces: // - application/json // responses: - // '204': + // 204: // description: no error - // '304': - // "$ref": "#/responses/ContainerAlreadyStoppedError" - // '404': - // "$ref": "#/responses/NoSuchContainer" - // '500': - // "$ref": "#/responses/InternalError" - r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/stop"), APIHandler(s.Context, handlers.StopContainer)).Methods(http.MethodPost) - // swagger:operation POST /libpod/containers/{nameOrID}/attach libpod attach + // 304: + // $ref: "#/responses/ContainerAlreadyStoppedError" + // 404: + // $ref: "#/responses/NoSuchContainer" + // 500: + // $ref: "#/responses/InternalError" + r.HandleFunc(VersionedPath("/libpod/containers/{name}/stop"), APIHandler(s.Context, handlers.StopContainer)).Methods(http.MethodPost) + // swagger:operation POST /libpod/containers/{name}/attach libpod libpodAttach // --- // tags: // - containers @@ -938,7 +1029,8 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // description: Hijacks the connection to forward the container's standard streams to the client. // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container // - in: query @@ -949,42 +1041,42 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // - in: query // name: logs // required: false - // type: bool + // type: boolean // description: Not yet supported // - in: query // name: stream // required: false - // type: bool + // type: boolean // default: true // description: If passed, must be set to true; stream=false is not yet supported // - in: query // name: stdout // required: false - // type: bool + // type: boolean // description: Attach to container STDOUT // - in: query // name: stderr // required: false - // type: bool + // type: boolean // description: Attach to container STDERR // - in: query // name: stdin // required: false - // type: bool + // type: boolean // description: Attach to container STDIN // produces: // - application/json // responses: - // '101': + // 101: // description: No error, connection has been hijacked for transporting streams. - // '400': - // "$ref": "#/responses/BadParamError" - // '404': - // "$ref": "#/responses/NoSuchContainer" - // '500': - // "$ref": "#/responses/InternalError" - r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/attach"), APIHandler(s.Context, handlers.AttachContainer)).Methods(http.MethodPost) - // swagger:operation POST /libpod/containers/{nameOrID}/resize libpod resize + // 400: + // $ref: "#/responses/BadParamError" + // 404: + // $ref: "#/responses/NoSuchContainer" + // 500: + // $ref: "#/responses/InternalError" + r.HandleFunc(VersionedPath("/libpod/containers/{name}/attach"), APIHandler(s.Context, handlers.AttachContainer)).Methods(http.MethodPost) + // swagger:operation POST /libpod/containers/{name}/resize libpod libpodResize // --- // tags: // - containers @@ -992,28 +1084,29 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // description: Resize the terminal attached to a container (for use with Attach). // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container // - in: query // name: h - // type: int + // type: integer // required: false // description: Height to set for the terminal, in characters // - in: query // name: w - // type: int + // type: integer // required: false // description: Width to set for the terminal, in characters // produces: // - application/json // responses: - // '200': - // description: no error - // '404': - // "$ref": "#/responses/NoSuchContainer" - // '500': - // "$ref": "#/responses/InternalError" - r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/resize"), APIHandler(s.Context, handlers.ResizeContainer)).Methods(http.MethodPost) + // 200: + // $ref: "#/responses/ok" + // 404: + // $ref: "#/responses/NoSuchContainer" + // 500: + // $ref: "#/responses/InternalError" + r.HandleFunc(VersionedPath("/libpod/containers/{name}/resize"), APIHandler(s.Context, handlers.ResizeContainer)).Methods(http.MethodPost) return nil } diff --git a/pkg/api/server/register_distribution.go b/pkg/api/server/register_distribution.go index 23820b4a7..b0ac61fb8 100644 --- a/pkg/api/server/register_distribution.go +++ b/pkg/api/server/register_distribution.go @@ -6,6 +6,6 @@ import ( ) func (s *APIServer) RegisterDistributionHandlers(r *mux.Router) error { - r.HandleFunc(VersionedPath("/distribution/{name:..*}/json"), handlers.UnsupportedHandler) + r.HandleFunc(VersionedPath("/distribution/{name}/json"), handlers.UnsupportedHandler) return nil } diff --git a/pkg/api/server/register_events.go b/pkg/api/server/register_events.go index 56cf96de1..a32244f4d 100644 --- a/pkg/api/server/register_events.go +++ b/pkg/api/server/register_events.go @@ -8,24 +8,29 @@ import ( func (s *APIServer) RegisterEventsHandlers(r *mux.Router) error { // swagger:operation GET /events system getEvents // --- + // tags: + // - system // summary: Returns events filtered on query parameters + // description: Returns events filtered on query parameters // produces: // - application/json // parameters: // - name: since + // type: string // in: query // description: start streaming events from this time // - name: until + // type: string // in: query // description: stop streaming events later than this // - name: filters + // type: string // in: query // description: JSON encoded map[string][]string of constraints // responses: - // "200": - // description: OK - // "500": - // description: Failed + // 200: + // $ref: "#/responses/ok" + // 500: // "$ref": "#/responses/InternalError" r.Handle(VersionedPath("/events"), APIHandler(s.Context, handlers.GetEvents)) return nil diff --git a/pkg/api/server/register_healthcheck.go b/pkg/api/server/register_healthcheck.go index e4cc145d5..1286324f0 100644 --- a/pkg/api/server/register_healthcheck.go +++ b/pkg/api/server/register_healthcheck.go @@ -8,6 +8,6 @@ import ( ) func (s *APIServer) registerHealthCheckHandlers(r *mux.Router) error { - r.Handle(VersionedPath("/libpod/containers/{name:..*}/runhealthcheck"), APIHandler(s.Context, libpod.RunHealthCheck)).Methods(http.MethodGet) + r.Handle(VersionedPath("/libpod/containers/{name}/runhealthcheck"), APIHandler(s.Context, libpod.RunHealthCheck)).Methods(http.MethodGet) return nil } diff --git a/pkg/api/server/register_images.go b/pkg/api/server/register_images.go index 8ea079654..c59d3d379 100644 --- a/pkg/api/server/register_images.go +++ b/pkg/api/server/register_images.go @@ -11,11 +11,10 @@ import ( func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // swagger:operation POST /images/create compat createImage - // // --- // tags: // - images (compat) - // summary: Create an image from an image + // summary: Create an image // description: Create an image by either pulling it from a registry or importing it. // produces: // - application/json @@ -25,53 +24,30 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // type: string // description: needs description // - in: query - // name: tag - // type: string - // description: needs description - // responses: - // '200': - // schema: - // items: - // $ref: "to be determined" - // '404': - // description: repo or image does not exist - // schema: - // $ref: "#/responses/InternalError" - // '500': - // description: unexpected error - // schema: - // $ref: '#/responses/GenericError' - r.Handle(VersionedPath("/images/create"), APIHandler(s.Context, generic.CreateImageFromImage)).Methods(http.MethodPost).Queries("fromImage", "{fromImage}") - // swagger:operation POST /images/create compat createImage - // --- - // tags: - // - images (compat) - // summary: Create an image from Source - // description: Create an image by either pulling it from a registry or importing it. - // produces: - // - application/json - // parameters: - // - in: query // name: fromSrc // type: string // description: needs description // - in: query - // name: changes - // type: to be determined + // name: tag + // type: string // description: needs description + // - in: header + // name: X-Registry-Auth + // type: string + // description: A base64-encoded auth configuration. + // - in: body + // name: request + // schema: + // type: string + // description: Image content if fromSrc parameter was used // responses: - // '200': - // schema: - // items: - // $ref: "to be determined" - // '404': - // description: repo or image does not exist - // schema: - // $ref: "#/responses/InternalError" - // '500': - // description: unexpected error - // schema: - // $ref: '#/responses/GenericError' + // 200: + // $ref: "#/responses/ok" + // 404: + // $ref: "#/responses/NoSuchImage" + // 500: + // $ref: "#/responses/InternalError" + r.Handle(VersionedPath("/images/create"), APIHandler(s.Context, generic.CreateImageFromImage)).Methods(http.MethodPost).Queries("fromImage", "{fromImage}") r.Handle(VersionedPath("/images/create"), APIHandler(s.Context, generic.CreateImageFromSrc)).Methods(http.MethodPost).Queries("fromSrc", "{fromSrc}") // swagger:operation GET /images/json compat listImages // --- @@ -79,20 +55,36 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // - images (compat) // summary: List Images // description: Returns a list of images on the server. Note that it uses a different, smaller representation of an image than inspecting a single image. + // parameters: + // - name: all + // in: query + // description: "Show all images. Only images from a final layer (no children) are shown by default." + // type: boolean + // default: false + // - name: filters + // in: query + // description: | + // A JSON encoded value of the filters (a `map[string][]string`) to process on the images list. Available filters: + // - `before`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`) + // - `dangling=true` + // - `label=key` or `label="key=value"` of an image label + // - `reference`=(`<image-name>[:<tag>]`) + // - `since`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`) + // type: string + // - name: digests + // in: query + // description: Not supported + // type: boolean + // default: false // produces: // - application/json // responses: - // '200': - // schema: - // type: array - // items: - // schema: - // $ref: "#/responses/DockerImageSummary" - // '500': - // $ref: '#/responses/InternalError' + // 200: + // $ref: "#/responses/DockerImageSummary" + // 500: + // $ref: '#/responses/InternalError' r.Handle(VersionedPath("/images/json"), APIHandler(s.Context, generic.GetImages)).Methods(http.MethodGet) - // swagger:operation POST /images/load compat loadImage - // + // swagger:operation POST /images/load compat importImage // --- // tags: // - images (compat) @@ -101,20 +93,21 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // parameters: // - in: query // name: quiet - // type: bool + // type: boolean // description: not supported // - in: body + // name: request // description: tarball of container image - // type: string - // format: binary + // schema: + // type: string // produces: // - application/json // responses: - // '200': + // 200: // description: no error - // '500': - // $ref: '#/responses/InternalError' - r.Handle(VersionedPath("/images/load"), APIHandler(s.Context, handlers.LoadImage)).Methods(http.MethodPost) + // 500: + // $ref: '#/responses/InternalError' + r.Handle(VersionedPath("/images/load"), APIHandler(s.Context, libpod.ImportImage)).Methods(http.MethodPost) // swagger:operation POST /images/prune compat pruneImages // --- // tags: @@ -135,12 +128,10 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // produces: // - application/json // responses: - // '200': - // schema: - // items: - // $ref: "#/responses/DocsImageDeleteResponse" - // '500': - // $ref: '#/responses/InternalError' + // 200: + // $ref: "#/responses/DocsImageDeleteResponse" + // 500: + // $ref: '#/responses/InternalError' r.Handle(VersionedPath("/images/prune"), APIHandler(s.Context, generic.PruneImages)).Methods(http.MethodPost) // swagger:operation GET /images/search compat searchImages // --- @@ -155,7 +146,7 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // description: term to search // - in: query // name: limit - // type: int + // type: integer // description: maximum number of results // - in: query // name: filters @@ -168,39 +159,44 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // produces: // - application/json // responses: - // '200': - // $ref: "#/responses/DocsSearchResponse" - // '500': - // $ref: '#/responses/InternalError' + // 200: + // $ref: "#/responses/DocsSearchResponse" + // 500: + // $ref: '#/responses/InternalError' r.Handle(VersionedPath("/images/search"), APIHandler(s.Context, handlers.SearchImages)).Methods(http.MethodGet) - // swagger:operation DELETE /images/{nameOrID} compat removeImage + // swagger:operation DELETE /images/{name} compat removeImage // --- // tags: // - images (compat) // summary: Remove Image // description: Delete an image from local storage // parameters: + // - in: path + // name: name + // type: string + // required: true + // description: name or ID of image to delete // - in: query // name: force - // type: bool + // type: boolean // description: remove the image even if used by containers or has other tags // - in: query // name: noprune - // type: bool + // type: boolean // description: not supported. will be logged as an invalid parameter if enabled // produces: // - application/json // responses: - // '200': - // $ref: "#/responses/DocsImageDeleteResponse" - // '404': - // $ref: '#/responses/NoSuchImage' - // '409': - // $ref: '#/responses/ConflictError' - // '500': - // $ref: '#/responses/InternalError' - r.Handle(VersionedPath("/images/{name:..*}"), APIHandler(s.Context, handlers.RemoveImage)).Methods(http.MethodDelete) - // swagger:operation GET /images/{nameOrID}/get compat exportImage + // 200: + // $ref: "#/responses/DocsImageDeleteResponse" + // 404: + // $ref: '#/responses/NoSuchImage' + // 409: + // $ref: '#/responses/ConflictError' + // 500: + // $ref: '#/responses/InternalError' + r.Handle(VersionedPath("/images/name"), APIHandler(s.Context, handlers.RemoveImage)).Methods(http.MethodDelete) + // swagger:operation GET /images/{name}/get compat exportImage // --- // tags: // - images (compat) @@ -208,21 +204,22 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // description: Export an image in tarball format // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container // produces: // - application/json // responses: - // '200': + // 200: // description: no error // schema: // type: string // format: binary - // '500': - // $ref: '#/responses/InternalError' - r.Handle(VersionedPath("/images/{name:..*}/get"), APIHandler(s.Context, generic.ExportImage)).Methods(http.MethodGet) - // swagger:operation GET /images/{nameOrID}/history compat imageHistory + // 500: + // $ref: '#/responses/InternalError' + r.Handle(VersionedPath("/images/{name}/get"), APIHandler(s.Context, generic.ExportImage)).Methods(http.MethodGet) + // swagger:operation GET /images/{name}/history compat imageHistory // --- // tags: // - images (compat) @@ -230,20 +227,21 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // description: Return parent layers of an image. // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container // produces: // - application/json // responses: - // '200': + // 200: // $ref: "#/responses/DocsHistory" - // '404': + // 404: // $ref: "#/responses/NoSuchImage" - // '500': + // 500: // $ref: "#/responses/InternalError" - r.Handle(VersionedPath("/images/{name:..*}/history"), APIHandler(s.Context, handlers.HistoryImage)).Methods(http.MethodGet) - // swagger:operation GET /images/{nameOrID}/json compat inspectImage + r.Handle(VersionedPath("/images/{name}/history"), APIHandler(s.Context, handlers.HistoryImage)).Methods(http.MethodGet) + // swagger:operation GET /images/{name}/json compat inspectImage // --- // tags: // - images (compat) @@ -251,20 +249,21 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // description: Return low-level information about an image. // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container // produces: // - application/json // responses: - // '200': - // $ref: "#/responses/DocsImageInspect" - // '404': - // $ref: "#/responses/NoSuchImage" - // '500': - // $ref: "#/responses/InternalError" - r.Handle(VersionedPath("/images/{name:..*}/json"), APIHandler(s.Context, generic.GetImage)) - // swagger:operation POST /images/{nameOrID}/tag compat tagImage + // 200: + // $ref: "#/responses/DocsImageInspect" + // 404: + // $ref: "#/responses/NoSuchImage" + // 500: + // $ref: "#/responses/InternalError" + r.Handle(VersionedPath("/images/{name}/json"), APIHandler(s.Context, generic.GetImage)) + // swagger:operation POST /images/{name}/tag compat tagImage // --- // tags: // - images (compat) @@ -272,7 +271,8 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // description: Tag an image so that it becomes part of a repository. // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container // - in: query @@ -296,7 +296,7 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // $ref: '#/responses/ConflictError' // 500: // $ref: '#/responses/InternalError' - r.Handle(VersionedPath("/images/{name:..*}/tag"), APIHandler(s.Context, handlers.TagImage)).Methods(http.MethodPost) + r.Handle(VersionedPath("/images/{name}/tag"), APIHandler(s.Context, handlers.TagImage)).Methods(http.MethodPost) // swagger:operation POST /commit/ compat commitContainer // --- // tags: @@ -325,7 +325,7 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // description: author of the image // - in: query // name: pause - // type: bool + // type: boolean // description: pause the container before committing it // - in: query // name: changes @@ -334,12 +334,12 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // produces: // - application/json // responses: - // '201': + // 201: // description: no error - // '404': - // $ref: '#/responses/NoSuchImage' - // '500': - // $ref: '#/responses/InternalError' + // 404: + // $ref: '#/responses/NoSuchImage' + // 500: + // $ref: '#/responses/InternalError' r.Handle(VersionedPath("/commit"), APIHandler(s.Context, generic.CommitContainer)).Methods(http.MethodPost) // swagger:operation POST /build images buildImage @@ -534,23 +534,28 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // - application/json // responses: // 200: - // description: OK (As of version 1.xx) - // schema: - // type: object - // required: - // - stream - // properties: - // stream: - // type: string - // example: | - // (build details...) - // Successfully built 8ba084515c724cbf90d447a63600c0a6 + // description: OK (As of version 1.xx) + // schema: + // type: object + // required: + // - stream + // properties: + // stream: + // type: string + // description: output from build process + // example: | + // (build details...) + // Successfully built 8ba084515c724cbf90d447a63600c0a6 + // 400: + // $ref: "#/responses/BadParamError" + // 500: + // $ref: "#/responses/InternalError" r.Handle(VersionedPath("/build"), APIHandler(s.Context, handlers.BuildImage)).Methods(http.MethodPost) /* libpod endpoints */ - // swagger:operation POST /libpod/images/{nameOrID}/exists libpod libpodImageExists + // swagger:operation POST /libpod/images/{name}/exists libpod libpodImageExists // --- // tags: // - images @@ -558,21 +563,22 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // description: Check if image exists in local store // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container // produces: // - application/json // responses: - // '204': + // 204: // description: image exists - // '404': - // $ref: '#/responses/NoSuchImage' - // '500': - // $ref: '#/responses/InternalError' - r.Handle(VersionedPath("/libpod/images/{name:..*}/exists"), APIHandler(s.Context, libpod.ImageExists)) - r.Handle(VersionedPath("/libpod/images/{name:..*}/tree"), APIHandler(s.Context, libpod.ImageTree)) - // swagger:operation GET /libpod/images/{nameOrID}/history libpod libpodImageHistory + // 404: + // $ref: '#/responses/NoSuchImage' + // 500: + // $ref: '#/responses/InternalError' + r.Handle(VersionedPath("/libpod/images/{name}/exists"), APIHandler(s.Context, libpod.ImageExists)) + r.Handle(VersionedPath("/libpod/images/{name}/tree"), APIHandler(s.Context, libpod.ImageTree)) + // swagger:operation GET /libpod/images/{name}/history libpod libpodImageHistory // --- // tags: // - images @@ -580,36 +586,56 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // description: Return parent layers of an image. // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container // produces: // - application/json // responses: - // '200': - // schema: - // items: - // $ref: "#/responses/HistoryResponse" - // '404': - // $ref: '#/responses/NoSuchImage' - // '500': - // $ref: '#/responses/InternalError' - r.Handle(VersionedPath("/libpod/images/history"), APIHandler(s.Context, handlers.HistoryImage)).Methods(http.MethodGet) + // 200: + // $ref: "#/responses/DocsHistory" + // 404: + // $ref: '#/responses/NoSuchImage' + // 500: + // $ref: '#/responses/InternalError' + r.Handle(VersionedPath("/libpod/images/{name}/history"), APIHandler(s.Context, handlers.HistoryImage)).Methods(http.MethodGet) // swagger:operation GET /libpod/images/json libpod libpodListImages // --- // tags: // - images // summary: List Images // description: Returns a list of images on the server + // parameters: + // - name: "all" + // in: "query" + // description: "Show all images. Only images from a final layer (no children) are shown by default." + // type: "boolean" + // default: false + // - name: "filters" + // in: "query" + // description: | + // A JSON encoded value of the filters (a `map[string][]string`) to process on the images list. Available filters: + // - `before`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`) + // - `dangling=true` + // - `label=key` or `label="key=value"` of an image label + // - `reference`=(`<image-name>[:<tag>]`) + // - `since`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`) + // type: "string" + // - name: "digests" + // in: "query" + // description: Not supported + // type: "boolean" + // default: false // produces: // - application/json // responses: - // '200': - // $ref: "#/responses/DockerImageSummary" - // '500': - // $ref: '#/responses/InternalError' + // 200: + // $ref: "#/responses/DockerImageSummary" + // 500: + // $ref: '#/responses/InternalError' r.Handle(VersionedPath("/libpod/images/json"), APIHandler(s.Context, libpod.GetImages)).Methods(http.MethodGet) - // swagger:operation POST /libpod/images/load libpod libpodLoadImage + // swagger:operation POST /libpod/images/load libpod libpodImportImage // --- // tags: // - images @@ -618,20 +644,30 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // parameters: // - in: query // name: quiet - // type: bool + // type: boolean // description: not supported + // - in: query + // name: change + // description: "Apply the following possible instructions to the created image (default []): CMD | ENTRYPOINT | ENV | EXPOSE | LABEL | STOPSIGNAL | USER | VOLUME | WORKDIR. JSON encoded string" + // type: string + // - in: query + // name: message + // description: Set commit message for imported image + // type: string // - in: body + // name: request // description: tarball of container image - // type: string - // format: binary + // required: true + // schema: + // type: string // produces: // - application/json // responses: - // '200': + // 200: // description: no error - // '500': + // 500: // $ref: '#/responses/InternalError' - r.Handle(VersionedPath("/libpod/images/load"), APIHandler(s.Context, handlers.LoadImage)).Methods(http.MethodPost) + r.Handle(VersionedPath("/libpod/images/load"), APIHandler(s.Context, libpod.ImportImage)).Methods(http.MethodPost) // swagger:operation POST /libpod/images/prune libpod libpodPruneImages // --- // tags: @@ -649,18 +685,13 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // (or `0`), all unused images are pruned. // - `until=<string>` Prune images created before this timestamp. The `<timestamp>` 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=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. - // - in: query - // name: all - // type: bool - // description: prune all images // produces: // - application/json // responses: - // '200': - // items: - // $ref: "#/responses/DocsImageDeleteResponse" - // '500': - // $ref: '#/responses/InternalError' + // 200: + // $ref: "#/responses/DocsImageDeleteResponse" + // 500: + // $ref: '#/responses/InternalError' r.Handle(VersionedPath("/libpod/images/prune"), APIHandler(s.Context, libpod.PruneImages)).Methods(http.MethodPost) // swagger:operation GET /libpod/images/search libpod libpodSearchImages // --- @@ -675,7 +706,7 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // description: term to search // - in: query // name: limit - // type: int + // type: integer // description: maximum number of results // - in: query // name: filters @@ -688,37 +719,42 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // produces: // - application/json // responses: - // '200': - // schema: - // items: - // $ref: "#/responses/DocsSearchResponse" - // '500': + // 200: + // $ref: "#/responses/DocsSearchResponse" + // 500: // $ref: '#/responses/InternalError' r.Handle(VersionedPath("/libpod/images/search"), APIHandler(s.Context, handlers.SearchImages)).Methods(http.MethodGet) - // swagger:operation DELETE /libpod/images/{nameOrID} libpod libpodRemoveImage + // swagger:operation DELETE /libpod/images/{name} libpod libpodRemoveImage // --- // tags: // - images // summary: Remove Image // description: Delete an image from local store // parameters: + // - in: path + // name: name + // type: string + // required: true + // description: name or ID of image to delete // - in: query // name: force - // type: bool + // type: boolean // description: remove the image even if used by containers or has other tags // produces: // - application/json // responses: - // '200': - // $ref: "#/responses/DocsImageDeleteResponse" - // '404': - // $ref: '#/responses/NoSuchImage' - // '409': - // $ref: '#/responses/ConflictError' - // '500': - // $ref: '#/responses/InternalError' - r.Handle(VersionedPath("/libpod/images/{name:..*}"), APIHandler(s.Context, handlers.RemoveImage)).Methods(http.MethodDelete) - // swagger:operation GET /libpod/images/{nameOrID}/get libpod libpoodExportImage + // 200: + // $ref: "#/responses/DocsImageDeleteResponse" + // 400: + // $ref: "#/responses/BadParamError" + // 404: + // $ref: '#/responses/NoSuchImage' + // 409: + // $ref: '#/responses/ConflictError' + // 500: + // $ref: '#/responses/InternalError' + r.Handle(VersionedPath("/libpod/images/name"), APIHandler(s.Context, handlers.RemoveImage)).Methods(http.MethodDelete) + // swagger:operation GET /libpod/images/{name}/get libpod libpoodExportImage // --- // tags: // - images @@ -726,33 +762,32 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // description: Export an image as a tarball // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container // - in: query // name: format // type: string // description: format for exported image - // default: oci-archive // - in: query // name: compress - // type: bool + // type: boolean // description: use compression on image - // default: false // produces: // - application/json // responses: - // '200': + // 200: // description: no error // schema: // type: string // format: binary - // '404': - // $ref: '#/responses/NoSuchImage' - // '500': - // $ref: '#/responses/InternalError' - r.Handle(VersionedPath("/libpod/images/{name:..*}/get"), APIHandler(s.Context, libpod.ExportImage)).Methods(http.MethodGet) - // swagger:operation GET /libpod/images/{nameOrID}/json libpod libpodInspectImage + // 404: + // $ref: '#/responses/NoSuchImage' + // 500: + // $ref: '#/responses/InternalError' + r.Handle(VersionedPath("/libpod/images/{name}/get"), APIHandler(s.Context, libpod.ExportImage)).Methods(http.MethodGet) + // swagger:operation GET /libpod/images/{name}/json libpod libpodInspectImage // --- // tags: // - images @@ -760,20 +795,21 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // description: Obtain low-level information about an image // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container // produces: // - application/json // responses: - // '200': - // $ref: "#/responses/DocsLibpodInspectImageResponse" - // '404': - // $ref: '#/responses/NoSuchImage' - // '500': - // $ref: '#/responses/InternalError' - r.Handle(VersionedPath("/libpod/images/{name:..*}/json"), APIHandler(s.Context, libpod.GetImage)) - // swagger:operation POST /libpod/images/{nameOrID}/tag libpod libpodTagImage + // 200: + // $ref: "#/responses/DocsLibpodInspectImageResponse" + // 404: + // $ref: '#/responses/NoSuchImage' + // 500: + // $ref: '#/responses/InternalError' + r.Handle(VersionedPath("/libpod/images/{name}/json"), APIHandler(s.Context, libpod.GetImage)) + // swagger:operation POST /libpod/images/{name}/tag libpod libpodTagImage // --- // tags: // - images @@ -781,7 +817,8 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // description: Tag an image so that it becomes part of a repository. // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the container // - in: query @@ -795,17 +832,17 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // produces: // - application/json // responses: - // '201': + // 201: // description: no error - // '400': - // $ref: '#/responses/BadParamError' - // '404': - // $ref: '#/responses/NoSuchImage' - // '409': - // $ref: '#/responses/ConflictError' - // '500': - // $ref: '#/responses/InternalError' - r.Handle(VersionedPath("/libpod/images/{name:..*}/tag"), APIHandler(s.Context, handlers.TagImage)).Methods(http.MethodPost) + // 400: + // $ref: '#/responses/BadParamError' + // 404: + // $ref: '#/responses/NoSuchImage' + // 409: + // $ref: '#/responses/ConflictError' + // 500: + // $ref: '#/responses/InternalError' + r.Handle(VersionedPath("/libpod/images/{name}/tag"), APIHandler(s.Context, handlers.TagImage)).Methods(http.MethodPost) return nil } diff --git a/pkg/api/server/register_info.go b/pkg/api/server/register_info.go index a7fb18721..8c50fed7f 100644 --- a/pkg/api/server/register_info.go +++ b/pkg/api/server/register_info.go @@ -10,15 +10,17 @@ import ( func (s *APIServer) registerInfoHandlers(r *mux.Router) error { // swagger:operation GET /info libpod libpodGetInfo // --- + // tags: + // - system // summary: Get info // description: Returns information on the system and libpod configuration // produces: // - application/json // responses: - // '200': + // 200: // description: to be determined - // '500': - // "$ref": "#/responses/InternalError" + // 500: + // $ref: "#/responses/InternalError" r.Handle(VersionedPath("/info"), APIHandler(s.Context, generic.GetInfo)).Methods(http.MethodGet) return nil } diff --git a/pkg/api/server/register_pods.go b/pkg/api/server/register_pods.go index 4018cfbe8..5c7b51871 100644 --- a/pkg/api/server/register_pods.go +++ b/pkg/api/server/register_pods.go @@ -16,81 +16,79 @@ func (s *APIServer) registerPodsHandlers(r *mux.Router) error { // parameters: // - in: query // name: filters - // descriptions: needs description and plumbing for filters + // type: string + // description: needs description and plumbing for filters // responses: - // '200': - // properties: - // items: - // $ref: "#/responses/ListPodsResponse" - // type: array - // '400': - // $ref: "#/responses/BadParamError" - // '500': - // $ref: "#/responses/InternalError" + // 200: + // $ref: "#/responses/ListPodsResponse" + // 400: + // $ref: "#/responses/BadParamError" + // 500: + // $ref: "#/responses/InternalError" r.Handle(VersionedPath("/libpod/pods/json"), APIHandler(s.Context, libpod.Pods)).Methods(http.MethodGet) r.Handle(VersionedPath("/libpod/pods/create"), APIHandler(s.Context, libpod.PodCreate)).Methods(http.MethodPost) // swagger:operation POST /libpod/pods/prune pods PrunePods // --- // summary: Prune unused pods - // parameters: - // - in: query - // name: force - // description: force delete - // type: bool - // default: false // produces: // - application/json // responses: - // '204': - // description: no error - // '400': - // $ref: "#/responses/BadParamError" - // '500': - // $ref: "#/responses/InternalError" + // 200: + // description: tbd + // schema: + // type: object + // additionalProperties: + // type: string + // 400: + // $ref: "#/responses/BadParamError" + // 500: + // $ref: "#/responses/InternalError" r.Handle(VersionedPath("/libpod/pods/prune"), APIHandler(s.Context, libpod.PodPrune)).Methods(http.MethodPost) - // swagger:operation DELETE /libpod/pods/{nameOrID} pods removePod + // swagger:operation DELETE /libpod/pods/{name} pods removePod // --- // summary: Remove pod // produces: // - application/json // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the pod // - in: query // name: force - // type: bool - // description: force delete + // type: boolean + // description : force removal of a running pod by first stopping all containers, then removing all containers in the pod // responses: - // '204': - // description: no error - // '400': - // $ref: "#/responses/BadParamError" - // '404': - // $ref: "#/responses/NoSuchPod" - // '500': - // $ref: "#/responses/InternalError" - r.Handle(VersionedPath("/libpod/pods/{name:..*}"), APIHandler(s.Context, libpod.PodDelete)).Methods(http.MethodDelete) - // swagger:operation GET /libpod/pods/{nameOrID}/json pods inspectPod + // 204: + // description: no error + // 400: + // $ref: "#/responses/BadParamError" + // 404: + // $ref: "#/responses/NoSuchPod" + // 500: + // $ref: "#/responses/InternalError" + r.Handle(VersionedPath("/libpod/pods/{name}"), APIHandler(s.Context, libpod.PodDelete)).Methods(http.MethodDelete) + // swagger:operation GET /libpod/pods/{name}/json pods inspectPod // --- // summary: Inspect pod // produces: // - application/json // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the pod // responses: - // '200': - // $ref: "#/responses/InspectPodResponse" - // '404': + // 200: + // $ref: "#/responses/InspectPodResponse" + // 404: // $ref: "#/responses/NoSuchPod" - // '500': + // 500: // $ref: "#/responses/InternalError" - r.Handle(VersionedPath("/libpod/pods/{name:..*}/json"), APIHandler(s.Context, libpod.PodInspect)).Methods(http.MethodGet) - // swagger:operation GET /libpod/pods/{nameOrID}/exists pods podExists + r.Handle(VersionedPath("/libpod/pods/{name}/json"), APIHandler(s.Context, libpod.PodInspect)).Methods(http.MethodGet) + // swagger:operation GET /libpod/pods/{name}/exists pods podExists // --- // summary: Pod exists // description: Check if a pod exists by name or ID @@ -98,25 +96,27 @@ func (s *APIServer) registerPodsHandlers(r *mux.Router) error { // - application/json // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the pod // responses: - // '204': - // description: pod exists - // '404': - // $ref: "#/responses/NoSuchPod" - // '500': - // $ref: "#/responses/InternalError" - r.Handle(VersionedPath("/libpod/pods/{name:..*}/exists"), APIHandler(s.Context, libpod.PodExists)).Methods(http.MethodGet) - // swagger:operation POST /libpod/pods/{nameOrID}/kill pods killPod + // 204: + // description: pod exists + // 404: + // $ref: "#/responses/NoSuchPod" + // 500: + // $ref: "#/responses/InternalError" + r.Handle(VersionedPath("/libpod/pods/{name}/exists"), APIHandler(s.Context, libpod.PodExists)).Methods(http.MethodGet) + // swagger:operation POST /libpod/pods/{name}/kill pods killPod // --- // summary: Kill a pod // produces: // - application/json // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the pod // - in: query @@ -125,116 +125,122 @@ func (s *APIServer) registerPodsHandlers(r *mux.Router) error { // description: signal to be sent to pod // default: SIGKILL // responses: - // '204': - // description: no error - // '400': - // $ref: "#/responses/BadParamError" - // '404': - // $ref: "#/responses/NoSuchPod" - // '409': - // $ref: "#/responses/ConflictError" - // '500': - // $ref: "#/responses/InternalError" - r.Handle(VersionedPath("/libpod/pods/{name:..*}/kill"), APIHandler(s.Context, libpod.PodKill)).Methods(http.MethodPost) - // swagger:operation POST /libpod/pods/{nameOrID}/pause pods pausePod + // 204: + // description: no error + // 400: + // $ref: "#/responses/BadParamError" + // 404: + // $ref: "#/responses/NoSuchPod" + // 409: + // $ref: "#/responses/ConflictError" + // 500: + // $ref: "#/responses/InternalError" + r.Handle(VersionedPath("/libpod/pods/{name}/kill"), APIHandler(s.Context, libpod.PodKill)).Methods(http.MethodPost) + // swagger:operation POST /libpod/pods/{name}/pause pods pausePod // --- // summary: Pause a pod + // description: Pause a pod // produces: // - application/json // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the pod // responses: - // '204': - // description: no error - // '404': - // $ref: "#/responses/NoSuchPod" - // '500': - // $ref: "#/responses/InternalError" - r.Handle(VersionedPath("/libpod/pods/{name:..*}/pause"), APIHandler(s.Context, libpod.PodPause)).Methods(http.MethodPost) - // swagger:operation POST /libpod/pods/{nameOrID}/restart pods restartPod + // 204: + // description: no error + // 404: + // $ref: "#/responses/NoSuchPod" + // 500: + // $ref: "#/responses/InternalError" + r.Handle(VersionedPath("/libpod/pods/{name}/pause"), APIHandler(s.Context, libpod.PodPause)).Methods(http.MethodPost) + // swagger:operation POST /libpod/pods/{name}/restart pods restartPod // --- // summary: Restart a pod // produces: // - application/json // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the pod // responses: - // '204': - // description: no error - // '404': - // $ref: "#/responses/NoSuchPod" - // '500': - // $ref: "#/responses/InternalError" - r.Handle(VersionedPath("/libpod/pods/{name:..*}/restart"), APIHandler(s.Context, libpod.PodRestart)).Methods(http.MethodPost) - // swagger:operation POST /libpod/pods/{nameOrID}/start pods startPod + // 204: + // description: no error + // 404: + // $ref: "#/responses/NoSuchPod" + // 500: + // $ref: "#/responses/InternalError" + r.Handle(VersionedPath("/libpod/pods/{name}/restart"), APIHandler(s.Context, libpod.PodRestart)).Methods(http.MethodPost) + // swagger:operation POST /libpod/pods/{name}/start pods startPod // --- // summary: Start a pod // produces: // - application/json // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the pod // responses: - // '204': - // description: no error - // '304': - // $ref: "#/responses/PodAlreadyStartedError" - // '404': - // $ref: "#/responses/NoSuchPod" - // '500': - // $ref: "#/responses/InternalError" - r.Handle(VersionedPath("/libpod/pods/{name:..*}/start"), APIHandler(s.Context, libpod.PodStart)).Methods(http.MethodPost) - // swagger:operation POST /libpod/pods/{nameOrID}/stop pods stopPod + // 204: + // description: no error + // 304: + // $ref: "#/responses/PodAlreadyStartedError" + // 404: + // $ref: "#/responses/NoSuchPod" + // 500: + // $ref: "#/responses/InternalError" + r.Handle(VersionedPath("/libpod/pods/{name}/start"), APIHandler(s.Context, libpod.PodStart)).Methods(http.MethodPost) + // swagger:operation POST /libpod/pods/{name}/stop pods stopPod // --- // summary: Stop a pod // produces: // - application/json // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the pod // - in: query // name: t - // type: int + // type: integer // description: timeout // responses: - // '204': - // description: no error - // '304': - // $ref: "#/responses/PodAlreadyStoppedError" - // '400': - // $ref: "#/responses/BadParamError" - // '404': - // $ref: "#/responses/NoSuchPod" - // '500': - // $ref: "#/responses/InternalError" - r.Handle(VersionedPath("/libpod/pods/{name:..*}/stop"), APIHandler(s.Context, libpod.PodStop)).Methods(http.MethodPost) - // swagger:operation POST /libpod/pods/{nameOrID}/unpause pods unpausePod + // 204: + // description: no error + // 304: + // $ref: "#/responses/PodAlreadyStoppedError" + // 400: + // $ref: "#/responses/BadParamError" + // 404: + // $ref: "#/responses/NoSuchPod" + // 500: + // $ref: "#/responses/InternalError" + r.Handle(VersionedPath("/libpod/pods/{name}/stop"), APIHandler(s.Context, libpod.PodStop)).Methods(http.MethodPost) + // swagger:operation POST /libpod/pods/{name}/unpause pods unpausePod // --- // summary: Unpause a pod // produces: // - application/json // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the pod // responses: - // '204': - // description: no error - // '404': - // $ref: "#/responses/NoSuchPod" - // '500': - // $ref: "#/responses/InternalError" - r.Handle(VersionedPath("/libpod/pods/{name:..*}/unpause"), APIHandler(s.Context, libpod.PodUnpause)).Methods(http.MethodPost) + // 204: + // description: no error + // 404: + // $ref: "#/responses/NoSuchPod" + // 500: + // $ref: "#/responses/InternalError" + r.Handle(VersionedPath("/libpod/pods/{name}/unpause"), APIHandler(s.Context, libpod.PodUnpause)).Methods(http.MethodPost) return nil } diff --git a/pkg/api/server/register_volumes.go b/pkg/api/server/register_volumes.go index 34138cfbf..d34c71238 100644 --- a/pkg/api/server/register_volumes.go +++ b/pkg/api/server/register_volumes.go @@ -31,12 +31,13 @@ func (s *APIServer) registerVolumeHandlers(r *mux.Router) error { // '500': // "$ref": "#/responses/InternalError" r.Handle("/libpod/volumes/prune", APIHandler(s.Context, libpod.PruneVolumes)).Methods(http.MethodPost) - // swagger:operation GET /volumes/{nameOrID}/json volumes inspectVolume + // swagger:operation GET /volumes/{name}/json volumes inspectVolume // --- // summary: Inspect volume // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the volume // produces: @@ -48,30 +49,31 @@ func (s *APIServer) registerVolumeHandlers(r *mux.Router) error { // "$ref": "#/responses/NoSuchVolume" // '500': // "$ref": "#/responses/InternalError" - r.Handle("/libpod/volumes/{name:..*}/json", APIHandler(s.Context, libpod.InspectVolume)).Methods(http.MethodGet) - // swagger:operation DELETE /volumes/{nameOrID} volumes removeVolume + r.Handle("/libpod/volumes/{name}/json", APIHandler(s.Context, libpod.InspectVolume)).Methods(http.MethodGet) + // swagger:operation DELETE /volumes/{name} volumes removeVolume // --- // summary: Remove volume // parameters: // - in: path - // name: nameOrID + // name: name + // type: string // required: true // description: the name or ID of the volume // - in: query // name: force - // type: bool + // type: boolean // description: force removal // produces: // - application/json // responses: - // '204': - // description: no error - // '400': - // "$ref": "#/responses/BadParamError" - // '404': - // "$ref": "#/responses/NoSuchVolume" - // '500': - // "$ref": "#/responses/InternalError" - r.Handle("/libpod/volumes/{name:..*}", APIHandler(s.Context, libpod.RemoveVolume)).Methods(http.MethodDelete) + // 204: + // description: no error + // 400: + // $ref: "#/responses/BadParamError" + // 404: + // $ref: "#/responses/NoSuchVolume" + // 500: + // $ref: "#/responses/InternalError" + r.Handle("/libpod/volumes/{name}", APIHandler(s.Context, libpod.RemoveVolume)).Methods(http.MethodDelete) return nil } diff --git a/pkg/api/server/server.go b/pkg/api/server/server.go index 69a44f21a..8c940763e 100644 --- a/pkg/api/server/server.go +++ b/pkg/api/server/server.go @@ -1,44 +1,3 @@ -// Package api Provides a container compatible interface. -// -// This documentation describes the HTTP Libpod interface. It is to be consider -// only as experimental as this point. The endpoints, parameters, inputs, and -// return values can all change. -// -// Schemes: http, https -// Host: podman.io -// BasePath: / -// Version: 0.0.1 -// License: Apache-2.0 https://opensource.org/licenses/Apache-2.0 -// Contact: Podman <podman@lists.podman.io> https://podman.io/community/ -// InfoExtensions: -// x-logo: -// - url: https://raw.githubusercontent.com/containers/libpod/master/logo/podman-logo.png -// - altText: "Podman logo" -// -// Consumes: -// - application/json -// - application/x-tar -// -// Produces: -// - application/json -// - text/plain -// - text/html -// -// tags: -// - name: containers -// description: Actions related to containers -// - name: images -// description: Actions related to images -// - name: pods -// description: Actions related to pods -// - name: volumes -// description: Actions related to volumes -// - name: containers (compat) -// description: Actions related to containers for the compatibility endpoints -// - name: images (compat) -// description: Actions related to images for the compatibility endpoints -// -// swagger:meta package server import ( @@ -52,6 +11,7 @@ import ( "time" "github.com/containers/libpod/libpod" + "github.com/containers/libpod/pkg/api/handlers" "github.com/coreos/go-systemd/activation" "github.com/gorilla/mux" "github.com/gorilla/schema" @@ -112,7 +72,7 @@ func newServer(runtime *libpod.Runtime, duration time.Duration, listener *net.Li ReadTimeout: 20 * time.Second, WriteTimeout: 2 * time.Minute, }, - Decoder: schema.NewDecoder(), + Decoder: handlers.NewAPIDecoder(), Context: nil, Runtime: runtime, Listener: *listener, @@ -126,6 +86,7 @@ func newServer(runtime *libpod.Runtime, duration time.Duration, listener *net.Li }) ctx, cancelFn := context.WithCancel(context.Background()) + server.CancelFunc = cancelFn // TODO: Use ConnContext when ported to go 1.13 ctx = context.WithValue(ctx, "decoder", server.Decoder) @@ -133,9 +94,6 @@ func newServer(runtime *libpod.Runtime, duration time.Duration, listener *net.Li ctx = context.WithValue(ctx, "shutdownFunc", server.Shutdown) server.Context = ctx - server.CancelFunc = cancelFn - server.Decoder.IgnoreUnknownKeys(true) - router.NotFoundHandler = http.HandlerFunc( func(w http.ResponseWriter, r *http.Request) { // We can track user errors... diff --git a/pkg/api/server/swagger.go b/pkg/api/server/swagger.go index dbf499ce7..5098390bc 100644 --- a/pkg/api/server/swagger.go +++ b/pkg/api/server/swagger.go @@ -41,7 +41,7 @@ type swagErrNoSuchPod struct { } } -// Internal error +// Internal server error // swagger:response InternalError type swagInternalError struct { // in:body @@ -50,16 +50,7 @@ type swagInternalError struct { } } -// Generic error -// swagger:response GenericError -type swagGenericError struct { - // in:body - Body struct { - utils.ErrorModel - } -} - -// Conflict error +// Conflict error in operation // swagger:response ConflictError type swagConflictError struct { // in:body @@ -68,7 +59,7 @@ type swagConflictError struct { } } -// Bad parameter +// Bad parameter in request // swagger:response BadParamError type swagBadParamError struct { // in:body @@ -130,7 +121,12 @@ type swagListContainers struct { } } -// To be determined -// swagger:response tbd -type swagTBD struct { +// Success +// swagger:response +type ok struct { + // in:body + Body struct { + // example: OK + ok string + } } |