diff options
| -rw-r--r-- | pkg/api/Makefile | 8 | ||||
| -rw-r--r-- | pkg/api/handlers/swagger.go | 4 | ||||
| -rw-r--r-- | pkg/api/handlers/utils/errors.go | 22 | ||||
| -rw-r--r-- | pkg/api/server/docs.go | 29 | ||||
| -rw-r--r-- | pkg/api/server/register_containers.go | 755 | ||||
| -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 | 403 | ||||
| -rw-r--r-- | pkg/api/server/register_info.go | 8 | ||||
| -rw-r--r-- | pkg/api/server/register_pods.go | 228 | ||||
| -rw-r--r-- | pkg/api/server/register_volumes.go | 32 | ||||
| -rw-r--r-- | pkg/api/server/server.go | 41 | ||||
| -rw-r--r-- | pkg/api/server/swagger.go | 26 |
14 files changed, 813 insertions, 760 deletions
diff --git a/pkg/api/Makefile b/pkg/api/Makefile index 915f0b9b3..f564b6516 100644 --- a/pkg/api/Makefile +++ b/pkg/api/Makefile @@ -2,12 +2,12 @@ export GO111MODULE=off SWAGGER_OUT ?= swagger.yaml +validate: ${SWAGGER_OUT} + swagger validate ${SWAGGER_OUT} + .PHONY: ${SWAGGER_OUT} ${SWAGGER_OUT}: # generate doesn't remove file on error rm -f ${SWAGGER_OUT} - swagger generate spec -o ${SWAGGER_OUT} -w ./ + swagger generate spec -o ${SWAGGER_OUT} -i tags.yaml -w ./ -# TODO: when pass validation move it under swagger. -validate: - swagger validate ${SWAGGER_OUT} diff --git a/pkg/api/handlers/swagger.go b/pkg/api/handlers/swagger.go index 0db4e19b6..5509c1d46 100644 --- a/pkg/api/handlers/swagger.go +++ b/pkg/api/handlers/swagger.go @@ -96,9 +96,7 @@ type swagLibpodInspectContainerResponse struct { // swagger:response ListPodsResponse type swagListPodsResponse struct { // in:body - Body struct { - libpod.PodInspect - } + Body []libpod.PodInspect } // Inspect pod diff --git a/pkg/api/handlers/utils/errors.go b/pkg/api/handlers/utils/errors.go index b6f125c58..9d2081cd8 100644 --- a/pkg/api/handlers/utils/errors.go +++ b/pkg/api/handlers/utils/errors.go @@ -27,34 +27,34 @@ func Error(w http.ResponseWriter, apiMessage string, code int, err error) { WriteJSON(w, code, em) } -func VolumeNotFound(w http.ResponseWriter, nameOrId string, err error) { +func VolumeNotFound(w http.ResponseWriter, name string, err error) { if errors.Cause(err) != define.ErrNoSuchVolume { InternalServerError(w, err) } - msg := fmt.Sprintf("No such volume: %s", nameOrId) + msg := fmt.Sprintf("No such volume: %s", name) Error(w, msg, http.StatusNotFound, err) } -func ContainerNotFound(w http.ResponseWriter, nameOrId string, err error) { +func ContainerNotFound(w http.ResponseWriter, name string, err error) { if errors.Cause(err) != define.ErrNoSuchCtr { InternalServerError(w, err) } - msg := fmt.Sprintf("No such container: %s", nameOrId) + msg := fmt.Sprintf("No such container: %s", name) Error(w, msg, http.StatusNotFound, err) } -func ImageNotFound(w http.ResponseWriter, nameOrId string, err error) { +func ImageNotFound(w http.ResponseWriter, name string, err error) { if errors.Cause(err) != define.ErrNoSuchImage { InternalServerError(w, err) } - msg := fmt.Sprintf("No such image: %s", nameOrId) + msg := fmt.Sprintf("No such image: %s", name) Error(w, msg, http.StatusNotFound, err) } -func PodNotFound(w http.ResponseWriter, nameOrId string, err error) { +func PodNotFound(w http.ResponseWriter, name string, err error) { if errors.Cause(err) != define.ErrNoSuchPod { InternalServerError(w, err) } - msg := fmt.Sprintf("No such pod: %s", nameOrId) + msg := fmt.Sprintf("No such pod: %s", name) Error(w, msg, http.StatusNotFound, err) } @@ -73,9 +73,11 @@ func BadRequest(w http.ResponseWriter, key string, value string, err error) { } type ErrorModel struct { - // root cause + // API root cause formatted for automated parsing + // example: API root cause Because string `json:"cause"` - // error message + // human error message, formatted for a human to read + // example: human error message Message string `json:"message"` } diff --git a/pkg/api/server/docs.go b/pkg/api/server/docs.go new file mode 100644 index 000000000..e028c6302 --- /dev/null +++ b/pkg/api/server/docs.go @@ -0,0 +1,29 @@ +// 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/ +// Extensions: +// 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..58920d106 100644 --- a/pkg/api/server/register_containers.go +++ b/pkg/api/server/register_containers.go @@ -23,21 +23,21 @@ 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" + // 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) // swagger:operation GET /containers/json compat listContainers // --- - // tags: - // - containers (compat) + // tags: + // - containers (compat) // summary: List containers // description: Returns a list of containers // parameters: @@ -63,17 +63,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 +87,78 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // produces: // - application/json // responses: - // '200': - // "$ref": "#/responses/DocsContainerPruneReport" - // '500': - // "$ref": "#/responses/InternalError" + // 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 + // 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 +166,28 @@ 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 // 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 +195,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 +221,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 +232,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,52 +247,55 @@ 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 @@ -297,16 +305,16 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // 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 +322,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 +387,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 +402,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,7 +424,8 @@ 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 @@ -421,14 +435,14 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // 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 +450,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 +462,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,29 +505,30 @@ 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 @@ -528,13 +544,12 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // 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 // --- @@ -545,8 +560,8 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // parameters: // - in: query // name: force - // type: bool - // description: something + // type: boolean + // description: TODO This should be removed from API. Will always be true... // - in: query // name: filters // type: string @@ -557,10 +572,12 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // produces: // - application/json // responses: - // '200': - // description: to be determined - // '500': - // "$ref": "#/responses/InternalError" + // 200: + // type: string + // description: success + // example: OK + // 500: + // $ref: "#/responses/InternalError" r.HandleFunc(VersionedPath("/libpod/containers/prune"), APIHandler(s.Context, libpod.PruneContainers)).Methods(http.MethodPost) // swagger:operation GET /libpod/containers/showmounted libpod showMounterContainers // --- @@ -571,48 +588,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 +639,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 +665,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 +694,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,51 +743,54 @@ 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 @@ -774,16 +800,16 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // 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,82 +817,89 @@ 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 @@ -876,14 +909,14 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // 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 +924,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 +973,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 +985,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 +1028,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..6e8b79313 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 // --- @@ -82,17 +58,12 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // 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 - // // --- // tags: // - images (compat) @@ -101,19 +72,20 @@ 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' + // 500: + // $ref: '#/responses/InternalError' r.Handle(VersionedPath("/images/load"), APIHandler(s.Context, handlers.LoadImage)).Methods(http.MethodPost) // swagger:operation POST /images/prune compat pruneImages // --- @@ -135,12 +107,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 +125,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 +138,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 +183,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 +206,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 +228,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 +250,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 +275,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 +304,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 +313,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 +513,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 +542,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,21 +565,20 @@ 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: @@ -604,10 +588,10 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // 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 // --- @@ -618,18 +602,20 @@ 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 + // 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) // swagger:operation POST /libpod/images/prune libpod libpodPruneImages @@ -651,16 +637,15 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // - `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 + // type: boolean // 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 +660,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 +673,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 +716,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 +749,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 +771,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 +786,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..1ef14b58c 100644 --- a/pkg/api/server/register_pods.go +++ b/pkg/api/server/register_pods.go @@ -16,17 +16,15 @@ 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 @@ -36,61 +34,63 @@ func (s *APIServer) registerPodsHandlers(r *mux.Router) error { // - in: query // name: force // description: force delete - // type: bool + // type: boolean // default: false // produces: // - application/json // responses: - // '204': - // description: no error - // '400': - // $ref: "#/responses/BadParamError" - // '500': - // $ref: "#/responses/InternalError" + // 204: + // description: no error + // 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 + // type: boolean // description: force delete // 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 +98,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 +127,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..847d11c3c 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 ( diff --git a/pkg/api/server/swagger.go b/pkg/api/server/swagger.go index dbf499ce7..f6643600a 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 @@ -59,7 +59,7 @@ type swagGenericError struct { } } -// Conflict error +// Conflict error in operation // swagger:response ConflictError type swagConflictError struct { // in:body @@ -68,7 +68,7 @@ type swagConflictError struct { } } -// Bad parameter +// Bad parameter in request // swagger:response BadParamError type swagBadParamError struct { // in:body @@ -134,3 +134,23 @@ type swagListContainers struct { // swagger:response tbd type swagTBD struct { } + +// Success +// swagger:response +type swag struct { + // in:body + Body struct { + // example: OK + ok string + } +} + +// Success +// swagger:response +type ok struct { + // in:body + Body struct { + // example: OK + ok string + } +} |