From cf7be58b2c160e2e1df737015c913fc1aff1dbe8 Mon Sep 17 00:00:00 2001 From: Brent Baude Date: Tue, 21 Jan 2020 12:44:50 -0600 Subject: Review corrections pass #2 Add API review comments to correct documentation and endpoints. Also, add a libpode prune method to reduce code duplication. Only used right now for the API but when the remote client is wired, we will switch over there too. Signed-off-by: Brent Baude --- pkg/api/server/register_containers.go | 96 +++++++++++++++++++++++++++-------- pkg/api/server/swagger.go | 24 --------- 2 files changed, 76 insertions(+), 44 deletions(-) (limited to 'pkg/api/server') diff --git a/pkg/api/server/register_containers.go b/pkg/api/server/register_containers.go index 58920d106..b2d2ab388 100644 --- a/pkg/api/server/register_containers.go +++ b/pkg/api/server/register_containers.go @@ -42,6 +42,20 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // 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: | @@ -91,7 +105,7 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // $ref: "#/responses/DocsContainerPruneReport" // 500: // $ref: "#/responses/InternalError" - r.HandleFunc(VersionedPath("/containers/prune"), APIHandler(s.Context, generic.PruneContainers)).Methods(http.MethodPost) + r.HandleFunc(VersionedPath("/containers/prune"), APIHandler(s.Context, handlers.PruneContainers)).Methods(http.MethodPost) // swagger:operation DELETE /containers/{name} compat removeContainer // --- // tags: @@ -175,6 +189,7 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // type: string // default: TERM // description: signal to be sent to container + // default: SIGKILL // produces: // - application/json // responses: @@ -301,7 +316,8 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // - 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- where is one of: a-z, @, ^, [, , or _." + // default: ctrl-p,ctrl-q // produces: // - application/json // responses: @@ -431,7 +447,7 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // - in: query // name: condition // type: string - // description: Wait until the container reaches the given condition + // description: not supported // produces: // - application/json // responses: @@ -541,6 +557,55 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // - 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=([:], , or ) + // - before=( or ) + // - expose=([/]|/[]) + // - exited= containers with exit code of + // - health=(starting|healthy|unhealthy|none) + // - id= a container's ID + // - is-task=(true|false) + // - label=key or label="key=value" of a container label + // - name= a container's name + // - network=( or ) + // - publish=([/]|/[]) + // - since=( or ) + // - status=(created|restarting|running|removing|paused|exited|dead) + // - volume=( or ) // produces: // - application/json // responses: @@ -551,18 +616,14 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // 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: boolean - // description: TODO This should be removed from API. Will always be true... - // - in: query // name: filters // type: string // description: | @@ -573,12 +634,10 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // - application/json // responses: // 200: - // type: string - // description: success - // example: OK + // $ref: "#/responses/DocsLibpodPruneResponse" // 500: // $ref: "#/responses/InternalError" - r.HandleFunc(VersionedPath("/libpod/containers/prune"), APIHandler(s.Context, libpod.PruneContainers)).Methods(http.MethodPost) + r.HandleFunc(VersionedPath("/libpod/containers/prune"), APIHandler(s.Context, handlers.PruneContainers)).Methods(http.MethodPost) // swagger:operation GET /libpod/containers/showmounted libpod showMounterContainers // --- // tags: @@ -796,7 +855,8 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // - 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- where is one of: a-z, @, ^, [, , or _." + // default: ctrl-p,ctrl-q // produces: // - application/json // responses: @@ -902,10 +962,6 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // 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: diff --git a/pkg/api/server/swagger.go b/pkg/api/server/swagger.go index f6643600a..5098390bc 100644 --- a/pkg/api/server/swagger.go +++ b/pkg/api/server/swagger.go @@ -50,15 +50,6 @@ type swagInternalError struct { } } -// Generic error -// swagger:response GenericError -type swagGenericError struct { - // in:body - Body struct { - utils.ErrorModel - } -} - // Conflict error in operation // swagger:response ConflictError type swagConflictError struct { @@ -130,21 +121,6 @@ type swagListContainers struct { } } -// To be determined -// 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 { -- cgit v1.2.3-54-g00ecf