diff options
| -rw-r--r-- | pkg/api/handlers/generic/config.go | 9 | ||||
| -rw-r--r-- | pkg/api/handlers/generic/containers_create.go | 6 | ||||
| -rw-r--r-- | pkg/api/handlers/generic/swagger.go | 24 | ||||
| -rw-r--r-- | pkg/api/server/register_containers.go | 251 | ||||
| -rw-r--r-- | pkg/api/server/register_events.go | 2 | ||||
| -rw-r--r-- | pkg/api/server/register_images.go | 201 | ||||
| -rw-r--r-- | pkg/api/server/register_info.go | 14 | ||||
| -rw-r--r-- | pkg/api/server/register_pods.go | 46 | ||||
| -rw-r--r-- | pkg/api/server/register_volumes.go | 16 | ||||
| -rw-r--r-- | pkg/api/server/swagger.go | 5 |
10 files changed, 280 insertions, 294 deletions
diff --git a/pkg/api/handlers/generic/config.go b/pkg/api/handlers/generic/config.go new file mode 100644 index 000000000..f715d25eb --- /dev/null +++ b/pkg/api/handlers/generic/config.go @@ -0,0 +1,9 @@ +package generic + +// ContainerCreateResponse is the response struct for creating a container +type ContainerCreateResponse struct { + // ID of the container created + Id string `json:"Id"` + // Warnings during container creation + Warnings []string `json:"Warnings"` +} diff --git a/pkg/api/handlers/generic/containers_create.go b/pkg/api/handlers/generic/containers_create.go index ef5337abd..f98872690 100644 --- a/pkg/api/handlers/generic/containers_create.go +++ b/pkg/api/handlers/generic/containers_create.go @@ -71,11 +71,7 @@ func CreateContainer(w http.ResponseWriter, r *http.Request) { return } - type ctrCreateResponse struct { - Id string `json:"Id"` - Warnings []string `json:"Warnings"` - } - response := ctrCreateResponse{ + response := ContainerCreateResponse{ Id: ctr.ID(), Warnings: []string{}} diff --git a/pkg/api/handlers/generic/swagger.go b/pkg/api/handlers/generic/swagger.go new file mode 100644 index 000000000..8df961b94 --- /dev/null +++ b/pkg/api/handlers/generic/swagger.go @@ -0,0 +1,24 @@ +package generic + +// Create container +// swagger:response ContainerCreateResponse +type swagCtrCreateResponse struct { + // in:body + Body struct { + ContainerCreateResponse + } +} + +// Wait container +// swagger:response ContainerWaitResponse +type swagCtrWaitResponse struct { + // in:body + Body struct { + // container exit code + StatusCode int + error message + Error struct { + Message string + } + } +} diff --git a/pkg/api/server/register_containers.go b/pkg/api/server/register_containers.go index af1881624..711aecc84 100644 --- a/pkg/api/server/register_containers.go +++ b/pkg/api/server/register_containers.go @@ -11,10 +11,8 @@ import ( func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // swagger:operation POST /containers/create containers createContainer - // - // Create a container - // // --- + // summary: Create a container // produces: // - application/json // parameters: @@ -24,44 +22,62 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // description: container name // responses: // '201': - // description: tbd + // $ref: "#/responses/ContainerCreateResponse" // '400': // "$ref": "#/responses/BadParamError" // '404': // "$ref": "#/responses/NoSuchContainer" // '409': - // "$ref": "#/types/ConflictError" + // "$ref": "#/responses/ConflictError" // '500': - // "$ref": "#/types/InternalError" + // "$ref": "#/responses/InternalError" r.HandleFunc(VersionedPath("/containers/create"), APIHandler(s.Context, generic.CreateContainer)).Methods(http.MethodPost) // swagger:operation GET /containers/json containers listContainers - // - // List containers - // // --- + // summary: List containers + // description: Returns a list of containers + // parameters: + // - in: query + // name: filters + // type: string + // description: | + // Returns a list of containers. + // - ancestor=(<image-name>[:<tag>], <image id>, or <image@digest>) + // - before=(<container id> or <container name>) + // - expose=(<port>[/<proto>]|<startport-endport>/[<proto>]) + // - exited=<int> containers with exit code of <int> + // - health=(starting|healthy|unhealthy|none) + // - id=<ID> a container's ID + // - is-task=(true|false) + // - label=key or label="key=value" of a container label + // - name=<name> a container's name + // - network=(<network id> or <network name>) + // - publish=(<port>[/<proto>]|<startport-endport>/[<proto>]) + // - since=(<container id> or <container name>) + // - status=(created|restarting|running|removing|paused|exited|dead) + // - volume=(<volume name> or <mount point destination>) // produces: // - application/json // responses: // '200': - // schema: - // type: array - // items: - // "$ref": "#/responses/Container" + // "$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 containers pruneContainers - // - // Prune unused containers - // // --- + // summary: Delete stopped containers + // description: Remove containers not in use // parameters: // - in: query // name: filters - // type: map[string][]string - // description: something + // type: string + // description: | + // Filters to process on the prune list, encoded as JSON (a `map[string][]string`). Available filters: + // - `until=<timestamp>` Prune containers created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time. + // - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. // produces: // - application/json // responses: @@ -71,10 +87,8 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // "$ref": "#/responses/InternalError" r.HandleFunc(VersionedPath("/containers/prune"), APIHandler(s.Context, generic.PruneContainers)).Methods(http.MethodPost) // swagger:operation DELETE /containers/{nameOrID} containers removeContainer - // - // Delete container - // // --- + // summary: Remove a container // parameters: // - in: path // name: nameOrID @@ -83,11 +97,13 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // - in: query // name: force // type: bool - // description: need something + // default: false + // description: If the container is running, kill it before removing it. // - in: query // name: v // type: bool - // description: need something + // default: false + // description: Remove the volumes associated with the container. // - in: query // name: link // type: bool @@ -107,15 +123,19 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // "$ref": "#/responses/InternalError" r.HandleFunc(VersionedPath("/containers/{name:..*}"), APIHandler(s.Context, generic.RemoveContainer)).Methods(http.MethodDelete) // swagger:operation GET /containers/{nameOrID}/json containers getContainer - // - // Inspect Container - // // --- + // summary: Inspect container + // description: Return low-level information about a container. // parameters: // - in: path // name: nameOrID // required: true - // description: the name or ID of the container + // description: the name or id of the container + // - in: query + // name: size + // type: bool + // default: false + // description: include the size of the container // produces: // - application/json // responses: @@ -126,11 +146,10 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // '500': // "$ref": "#/responses/InternalError" r.HandleFunc(VersionedPath("/containers/{name:..*}/json"), APIHandler(s.Context, generic.GetContainer)).Methods(http.MethodGet) - // swagger:operation POST /containers/{nameOrID}/kill containers killContainer - // - // Kill Container - // + // swagger:operation post /containers/{nameOrID}/kill containers killcontainer // --- + // summary: Kill container + // description: Signal to send to the container as an integer or string (e.g. SIGINT) // parameters: // - in: path // name: nameOrID @@ -153,10 +172,9 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // "$ref": "#/responses/InternalError" r.HandleFunc(VersionedPath("/containers/{name:..*}/kill"), APIHandler(s.Context, generic.KillContainer)).Methods(http.MethodPost) // swagger:operation GET /containers/{nameOrID}/logs containers LogsFromContainer - // - // Get logs from container - // // --- + // summary: Get container logs + // description: Get stdout and stderr logs from a container. // parameters: // - in: path // name: nameOrID @@ -165,46 +183,47 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // - in: query // name: follow // type: bool - // description: needs description + // description: Keep connection after returning logs. // - in: query // name: stdout // type: bool - // description: needs description + // description: not supported // - in: query // name: stderr // type: bool - // description: needs description + // description: not supported? // - in: query // name: since // type: string - // description: needs description + // description: Only return logs since this time, as a UNIX timestamp // - in: query // name: until // type: string - // description: needs description + // description: Only return logs before this time, as a UNIX timestamp // - in: query // name: timestamps // type: bool - // description: needs description + // default: false + // description: Add timestamps to every log line // - in: query // name: tail // type: string - // description: needs description + // description: Only return this number of log lines from the end of the logs + // default: all // produces: // - application/json // responses: // '200': - // description: tbd + // 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 containers pauseContainer - // - // Pause Container - // // --- + // summary: Pause container + // description: Use the cgroups freezer to suspend all processes in a container. // parameters: // - in: path // name: nameOrID @@ -222,10 +241,8 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { 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 containers restartContainer - // - // Restart Container - // // --- + // summary: Restart container // parameters: // - in: path // name: nameOrID @@ -246,10 +263,8 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // "$ref": "#/responses/InternalError" r.HandleFunc(VersionedPath("/containers/{name:..*}/restart"), APIHandler(s.Context, handlers.RestartContainer)).Methods(http.MethodPost) // swagger:operation POST /containers/{nameOrID}/start containers startContainer - // - // Start a container - // // --- + // summary: Start a container // parameters: // - in: path // name: nameOrID @@ -272,10 +287,9 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // "$ref": "#/responses/InternalError" r.HandleFunc(VersionedPath("/containers/{name:..*}/start"), APIHandler(s.Context, handlers.StartContainer)).Methods(http.MethodPost) // swagger:operation GET /containers/{nameOrID}/stats containers statsContainer - // - // Get stats for a container - // // --- + // summary: Get stats for a container + // description: This returns a live stream of a container’s resource usage statistics. // parameters: // - in: path // name: nameOrID @@ -284,24 +298,21 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // - in: query // name: stream // type: bool - // description: needs description + // default: true + // description: Stream the output // produces: // - application/json // responses: - // '204': - // description: tbd - // '304': - // "$ref": "#/responses/ContainerAlreadyStartedError" + // '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 containers stopContainer - // - // Stop a container - // // --- + // summary: Stop a container // parameters: // - in: path // name: nameOrID @@ -324,10 +335,8 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // "$ref": "#/responses/InternalError" r.HandleFunc(VersionedPath("/containers/{name:..*}/stop"), APIHandler(s.Context, handlers.StopContainer)).Methods(http.MethodPost) // swagger:operation GET /containers/{nameOrID}/top containers topContainer - // - // List processes running inside a container - // // --- + // summary: List processes running inside a container // parameters: // - in: path // name: nameOrID @@ -348,10 +357,9 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // "$ref": "#/responses/InternalError" r.HandleFunc(VersionedPath("/containers/{name:..*}/top"), APIHandler(s.Context, handlers.TopContainer)).Methods(http.MethodGet) // swagger:operation POST /containers/{nameOrID}/unpause containers unpauseContainer - // - // Unpause Container - // // --- + // summary: Unpause container + // description: Resume a paused container // parameters: // - in: path // name: nameOrID @@ -362,17 +370,15 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // responses: // '204': // description: no error - // schema: // '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 containers waitContainer - // - // Wait on a container to exit - // // --- + // summary: Wait on a container to exit + // description: Block until a container stops, then returns the exit code. // parameters: // - in: path // name: nameOrID @@ -385,8 +391,8 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // produces: // - application/json // responses: - // '204': - // description: no error + // '200': + // $ref: "#/responses/ContainerWaitResponse" // '404': // "$ref": "#/responses/NoSuchContainer" // '500': @@ -398,11 +404,10 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { */ r.HandleFunc(VersionedPath("/libpod/containers/create"), APIHandler(s.Context, libpod.CreateContainer)).Methods(http.MethodPost) - // swagger:operation GET /libpod/containers/json containers listContainers - // - // List containers - // + // swagger:operation GET /libpod/containers/json containers libpodListContainers // --- + // summary: List containers + // description: Returns a list of containers // produces: // - application/json // responses: @@ -416,11 +421,10 @@ 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 containers pruneContainers - // - // Prune unused containers - // + // swagger:operation POST /libpod/containers/prune containers libpodPruneContainers // --- + // summary: Prune unused containers + // description: Remove stopped and exited containers // parameters: // - in: query // name: force @@ -428,21 +432,23 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // description: something // - in: query // name: filters - // type: map[string][]string - // description: something + // type: string + // description: | + // Filters to process on the prune list, encoded as JSON (a `map[string][]string`). Available filters: + // - `until=<timestamp>` Prune containers created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time. + // - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. // produces: // - application/json // responses: // '200': - // description: TBD + // description: to be determined // '500': // "$ref": "#/responses/InternalError" r.HandleFunc(VersionedPath("/libpod/containers/prune"), APIHandler(s.Context, libpod.PruneContainers)).Methods(http.MethodPost) // swagger:operation GET /libpod/containers/showmounted containers showMounterContainers - // - // Show mounted containers - // // --- + // summary: Show mounted containers + // description: Lists all mounted containers mount points // produces: // - application/json // responses: @@ -455,11 +461,9 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // '500': // "$ref": "#/responses/InternalError" r.HandleFunc(VersionedPath("/libpod/containers/showmounted"), APIHandler(s.Context, libpod.ShowMountedContainers)).Methods(http.MethodGet) - // swagger:operation DELETE /libpod/containers/json containers removeContainer - // - // Delete container - // + // swagger:operation DELETE /libpod/containers/json containers libpodRemoveContainer // --- + // summary: Delete container // parameters: // - in: path // name: nameOrID @@ -472,7 +476,7 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // - in: query // name: v // type: bool - // description: need something + // description: delete volumes // produces: // - application/json // responses: @@ -487,11 +491,10 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // '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 containers getContainer - // - // Inspect Container - // + // swagger:operation GET /libpod/containers/{nameOrID}/json containers libpodGetContainer // --- + // summary: Inspect container + // description: Return low-level information about a container. // parameters: // - in: path // name: nameOrID @@ -511,11 +514,10 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // '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 containers killContainer - // - // Kill Container - // + // swagger:operation POST /libpod/containers/{nameOrID}/kill containers libpodKillContainer // --- + // summary: Kill container + // description: send a signal to a container, defaults to killing the container // parameters: // - in: path // name: nameOrID @@ -539,10 +541,9 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // "$ref": "#/responses/InternalError" r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/kill"), APIHandler(s.Context, libpod.KillContainer)).Methods(http.MethodGet) // swagger:operation GET /libpod/containers/{nameOrID}/mount containers mountContainer - // - // Mount a container - // // --- + // summary: Mount a container + // description: Mount a container to the filesystem // parameters: // - in: path // name: nameOrID @@ -563,11 +564,10 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // "$ref": "#/responses/InternalError" r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/mount"), APIHandler(s.Context, libpod.MountContainer)).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 containers pauseContainer - // - // Pause Container - // + // swagger:operation POST /libpod/containers/{nameOrID}/pause containers libpodPauseContainer // --- + // summary: Pause a container + // description: Use the cgroups freezer to suspend all processes in a container. // parameters: // - in: path // name: nameOrID @@ -583,11 +583,9 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // '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 containers restartContainer - // - // Restart Container - // + // swagger:operation POST /libpod/containers/{nameOrID}/restart containers libpodRestartContainer // --- + // summary: Restart a container // parameters: // - in: path // name: nameOrID @@ -607,11 +605,9 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // '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 containers startContainer - // - // Start a container - // + // swagger:operation POST /libpod/containers/{nameOrID}/start containers libpodStartContainer // --- + // summary: Start a container // parameters: // - in: path // name: nameOrID @@ -635,11 +631,9 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/start"), APIHandler(s.Context, handlers.StartContainer)).Methods(http.MethodPost) r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/stats"), APIHandler(s.Context, libpod.StatsContainer)).Methods(http.MethodGet) r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/top"), APIHandler(s.Context, handlers.TopContainer)).Methods(http.MethodGet) - // swagger:operation POST /libpod/containers/{nameOrID}/unpause containers unpauseContainer - // - // Unpause Container - // + // swagger:operation POST /libpod/containers/{nameOrID}/unpause containers libpodUnpauseContainer // --- + // summary: Unpause Container // parameters: // - in: path // name: nameOrID @@ -655,11 +649,9 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // '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 containers waitContainer - // - // Wait on a container to exit - // + // swagger:operation POST /libpod/containers/{nameOrID}/wait containers libpodWaitContainer // --- + // summary: Wait on a container to exit // parameters: // - in: path // name: nameOrID @@ -680,10 +672,9 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // "$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 containers containerExists - // - // Check if container exists - // // --- + // summary: Check if container exists + // description: Quick way to determine if a container exists by name or ID // parameters: // - in: path // name: nameOrID @@ -699,11 +690,9 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error { // '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 containers stopContainer - // - // Stop a container - // + // swagger:operation POST /libpod/containers/{nameOrID}/stop containers libpodStopContainer // --- + // summary: Stop a container // parameters: // - in: path // name: nameOrID diff --git a/pkg/api/server/register_events.go b/pkg/api/server/register_events.go index d764fdbb4..56cf96de1 100644 --- a/pkg/api/server/register_events.go +++ b/pkg/api/server/register_events.go @@ -26,7 +26,7 @@ func (s *APIServer) RegisterEventsHandlers(r *mux.Router) error { // description: OK // "500": // description: Failed - // "$ref": "#/types/errorModel" + // "$ref": "#/responses/InternalError" r.Handle(VersionedPath("/events"), APIHandler(s.Context, handlers.GetEvents)) return nil } diff --git a/pkg/api/server/register_images.go b/pkg/api/server/register_images.go index 488427f3c..7298f3c61 100644 --- a/pkg/api/server/register_images.go +++ b/pkg/api/server/register_images.go @@ -12,9 +12,9 @@ import ( func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // swagger:operation POST /images/create images createImage // - // Create an image from an image - // // --- + // summary: Create an image from an image + // description: Create an image by either pulling it from a registry or importing it. // produces: // - application/json // parameters: @@ -30,21 +30,20 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // '200': // schema: // items: - // $ref: "TBD" + // $ref: "to be determined" // '404': // description: repo or image does not exist // schema: - // $ref: "#/responses/generalError" + // $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 images createImage - // - // Create an image from Source - // // --- + // summary: Create an image from Source + // description: Create an image by either pulling it from a registry or importing it. // produces: // - application/json // parameters: @@ -54,27 +53,26 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // description: needs description // - in: query // name: changes - // type: TBD + // type: to be determined // description: needs description // responses: // '200': // schema: // items: - // $ref: "TBD" + // $ref: "to be determined" // '404': // description: repo or image does not exist // schema: - // $ref: "#/responses/generalError" + // $ref: "#/responses/InternalError" // '500': // description: unexpected error // schema: // $ref: '#/responses/GenericError' r.Handle(VersionedPath("/images/create"), APIHandler(s.Context, generic.CreateImageFromSrc)).Methods(http.MethodPost).Queries("fromSrc", "{fromSrc}") // swagger:operation GET /images/json images listImages - // - // List Images - // // --- + // summary: List Images + // description: Returns a list of images on the server. Note that it uses a different, smaller representation of an image than inspecting a single image. // produces: // - application/json // responses: @@ -89,32 +87,41 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { r.Handle(VersionedPath("/images/json"), APIHandler(s.Context, generic.GetImages)).Methods(http.MethodGet) // swagger:operation POST /images/load images loadImage // - // Import image - // // --- + // summary: Import image + // description: Load a set of images and tags into a repository. // parameters: // - in: query // name: quiet // type: bool // description: not supported + // - in: body + // description: tarball of container image + // type: string + // format: binary // produces: // - application/json // responses: // '200': - // description: TBD + // description: no error // '500': // $ref: '#/responses/InternalError' r.Handle(VersionedPath("/images/load"), APIHandler(s.Context, handlers.LoadImage)).Methods(http.MethodPost) // swagger:operation POST /images/prune images pruneImages - // - // Prune unused images - // // --- + // summary: Prune unused images + // description: Remove images from local storage that are not being used by a container // parameters: // - in: query // name: filters - // type: map[string][]string - // description: not supported + // type: string + // description: | + // filters to apply to image pruning, encoded as JSON (map[string][]string). Available filters: + // - `dangling=<boolean>` When set to `true` (or `1`), prune only + // unused *and* untagged images. When set to `false` + // (or `0`), all unused images are pruned. + // - `until=<string>` Prune images created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time. + // - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. // produces: // - application/json // responses: @@ -126,10 +133,9 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // $ref: '#/responses/InternalError' r.Handle(VersionedPath("/images/prune"), APIHandler(s.Context, generic.PruneImages)).Methods(http.MethodPost) // swagger:operation GET /images/search images searchImages - // - // Search images - // // --- + // summary: Search images + // description: Search registries for an image // parameters: // - in: query // name: term @@ -141,8 +147,12 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // description: maximum number of results // - in: query // name: filters - // type: map[string][]string - // description: TBD + // type: string + // description: | + // A JSON encoded value of the filters (a `map[string][]string`) to process on the images list. Available filters: + // - `is-automated=(true|false)` + // - `is-official=(true|false)` + // - `stars=<number>` Matches images that has at least 'number' stars. // produces: // - application/json // responses: @@ -152,10 +162,9 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // $ref: '#/responses/InternalError' r.Handle(VersionedPath("/images/search"), APIHandler(s.Context, handlers.SearchImages)).Methods(http.MethodGet) // swagger:operation DELETE /images/{nameOrID} images removeImage - // - // Remove Image - // // --- + // summary: Remove Image + // description: Delete an image from local storage // parameters: // - in: query // name: force @@ -178,10 +187,9 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // $ref: '#/responses/InternalError' r.Handle(VersionedPath("/images/{name:..*}"), APIHandler(s.Context, handlers.RemoveImage)).Methods(http.MethodDelete) // swagger:operation GET /images/{nameOrID}/get images exportImage - // - // Export an image - // // --- + // summary: Export an image + // description: Export an image in tarball format // parameters: // - in: path // name: nameOrID @@ -191,17 +199,14 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // - application/json // responses: // '200': - // schema: - // $ref: "TBD" - // description: TBD + // description: no error // '500': // $ref: '#/responses/InternalError' r.Handle(VersionedPath("/images/{name:..*}/get"), APIHandler(s.Context, generic.ExportImage)).Methods(http.MethodGet) // swagger:operation GET /images/{nameOrID}/history images imageHistory - // - // History of an image - // // --- + // summary: History of an image + // description: Return parent layers of an image. // parameters: // - in: path // name: nameOrID @@ -218,10 +223,9 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // $ref: "#/responses/InternalError" r.Handle(VersionedPath("/images/{name:..*}/history"), APIHandler(s.Context, handlers.HistoryImage)).Methods(http.MethodGet) // swagger:operation GET /images/{nameOrID}/json images inspectImage - // - // Inspect an image - // // --- + // summary: Inspect an image + // description: Return low-level information about an image. // parameters: // - in: path // name: nameOrID @@ -238,10 +242,9 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // $ref: "#/responses/InternalError" r.Handle(VersionedPath("/images/{name:..*}/json"), APIHandler(s.Context, generic.GetImage)) // swagger:operation POST /images/{nameOrID}/tag images tagImage - // - // Tag an image - // // --- + // summary: Tag an image + // description: Tag an image so that it becomes part of a repository. // parameters: // - in: path // name: nameOrID @@ -270,10 +273,8 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // $ref: '#/responses/InternalError' r.Handle(VersionedPath("/images/{name:..*}/tag"), APIHandler(s.Context, handlers.TagImage)).Methods(http.MethodPost) // swagger:operation POST /commit/ commit commitContainer - // - // Create a new image from a container - // // --- + // summary: Create a new image from a container // parameters: // - in: query // name: container @@ -318,11 +319,10 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { libpod endpoints */ - // swagger:operation POST /libpod/images/{nameOrID}/exists images imageExists - // - // Check if image exists in local store - // + // swagger:operation POST /libpod/images/{nameOrID}/exists images libpodImageExists // --- + // summary: Image exists + // description: Check if image exists in local store // parameters: // - in: path // name: nameOrID @@ -330,15 +330,6 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // description: the name or ID of the container // produces: // - application/json - // parameters: - // - in: query - // name: fromImage - // type: string - // description: needs description - // - in: query - // name: tag - // type: string - // description: needs description // responses: // '204': // description: image exists @@ -348,11 +339,10 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // $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 images imageHistory - // - // History of an image - // + // swagger:operation GET /libpod/images/{nameOrID}/history images libpodImageHistory // --- + // summary: History of an image + // description: Return parent layers of an image. // parameters: // - in: path // name: nameOrID @@ -370,11 +360,10 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // '500': // $ref: '#/responses/InternalError' r.Handle(VersionedPath("/libpod/images/history"), APIHandler(s.Context, handlers.HistoryImage)).Methods(http.MethodGet) - // swagger:operation GET /libpod/images/json images listImages - // - // List Images - // + // swagger:operation GET /libpod/images/json images libpodListImages // --- + // summary: List Images + // description: Returns a list of images on the server // produces: // - application/json // responses: @@ -385,34 +374,42 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // '500': // $ref: '#/responses/InternalError' r.Handle(VersionedPath("/libpod/images/json"), APIHandler(s.Context, libpod.GetImages)).Methods(http.MethodGet) - // swagger:operation POST /libpod/images/load images loadImage - // - // Import image - // + // swagger:operation POST /libpod/images/load images libpodLoadImage // --- + // summary: Import image + // description: tbd // parameters: // - in: query // name: quiet // type: bool // description: not supported + // - in: body + // description: tarball of container image + // type: string + // format: binary // produces: // - application/json // responses: // '200': - // description: TBD + // description: no error // '500': // $ref: '#/responses/InternalError' r.Handle(VersionedPath("/libpod/images/load"), APIHandler(s.Context, handlers.LoadImage)).Methods(http.MethodPost) - // swagger:operation POST /libpod/images/prune images pruneImages - // - // Prune unused images - // + // swagger:operation POST /libpod/images/prune images libpodPruneImages // --- + // summary: Prune unused images + // description: Remove images that are not being used by a container // parameters: // - in: query // name: filters - // type: map[string][]string - // description: image filters + // type: string + // description: | + // filters to apply to image pruning, encoded as JSON (map[string][]string). Available filters: + // - `dangling=<boolean>` When set to `true` (or `1`), prune only + // unused *and* untagged images. When set to `false` + // (or `0`), all unused images are pruned. + // - `until=<string>` Prune images created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time. + // - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. // - in: query // name: all // type: bool @@ -421,17 +418,15 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // - application/json // responses: // '200': - // schema: // items: // $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 images searchImages - // - // Search images - // + // swagger:operation GET /libpod/images/search images libpodSearchImages // --- + // summary: Search images + // description: Search registries for images // parameters: // - in: query // name: term @@ -443,8 +438,12 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // description: maximum number of results // - in: query // name: filters - // type: map[string][]string - // description: TBD + // type: string + // description: | + // A JSON encoded value of the filters (a `map[string][]string`) to process on the images list. Available filters: + // - `is-automated=(true|false)` + // - `is-official=(true|false)` + // - `stars=<number>` Matches images that has at least 'number' stars. // produces: // - application/json // responses: @@ -455,11 +454,10 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // '500': // $ref: '#/responses/InternalError' r.Handle(VersionedPath("/libpod/images/search"), APIHandler(s.Context, handlers.SearchImages)).Methods(http.MethodGet) - // swagger:operation DELETE /libpod/images/{nameOrID} images removeImage - // - // Remove Image - // + // swagger:operation DELETE /libpod/images/{nameOrID} images libpodRemoveImage // --- + // summary: Remove Image + // description: Delete an image from local store // parameters: // - in: query // name: force @@ -483,11 +481,10 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // '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 images exportImage - // - // Export an image - // + // swagger:operation GET /libpod/images/{nameOrID}/get images libpoodExportImage // --- + // summary: Export an image + // description: Export an image as a tarball // parameters: // - in: path // name: nameOrID @@ -505,17 +502,16 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // - application/json // responses: // '200': - // description: TBD + // description: no error // '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 images inspectImage - // - // Inspect an image - // + // swagger:operation GET /libpod/images/{nameOrID}/json images libpodInspectImage // --- + // summary: Inspect an image + // description: Obtain low-level information about an image // parameters: // - in: path // name: nameOrID @@ -533,11 +529,10 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error { // '500': // $ref: '#/responses/InternalError' r.Handle(VersionedPath("/libpod/images/{name:..*}/json"), APIHandler(s.Context, libpod.GetImage)) - // swagger:operation POST /libpod/images/{nameOrID}/tag images tagImage - // - // Tag an image - // + // swagger:operation POST /libpod/images/{nameOrID}/tag images libpodTagImage // --- + // summary: Tag an image + // description: Tag an image so that it becomes part of a repository. // parameters: // - in: path // name: nameOrID diff --git a/pkg/api/server/register_info.go b/pkg/api/server/register_info.go index 797158553..a7fb18721 100644 --- a/pkg/api/server/register_info.go +++ b/pkg/api/server/register_info.go @@ -8,21 +8,17 @@ import ( ) func (s *APIServer) registerInfoHandlers(r *mux.Router) error { - // swagger:operation GET /info libpod getInfo - // - // Returns information on the system and libpod configuration - // + // swagger:operation GET /info libpod libpodGetInfo // --- + // summary: Get info + // description: Returns information on the system and libpod configuration // produces: // - application/json // responses: // '200': - // schema: - // "$ref": "#/types/Info" + // description: to be determined // '500': - // description: unexpected error - // schema: - // "$ref": "#/types/ErrorModel" + // "$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 c2e10277e..1f09e8f0e 100644 --- a/pkg/api/server/register_pods.go +++ b/pkg/api/server/register_pods.go @@ -9,10 +9,8 @@ import ( func (s *APIServer) registerPodsHandlers(r *mux.Router) error { // swagger:operation GET /libpod/pods/json pods ListPods - // - // List Pods - // // --- + // summary: List pods // produces: // - application/json // parameters: @@ -29,15 +27,14 @@ func (s *APIServer) registerPodsHandlers(r *mux.Router) error { 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 - // - // Prune unused pods - // // --- + // summary: Prune unused pods // parameters: // - in: query // name: force // description: force delete // type: bool + // default: false // produces: // - application/json // responses: @@ -49,10 +46,8 @@ func (s *APIServer) registerPodsHandlers(r *mux.Router) error { // $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 - // - // Remove Pod - // // --- + // summary: Remove pod // produces: // - application/json // parameters: @@ -75,10 +70,8 @@ func (s *APIServer) registerPodsHandlers(r *mux.Router) error { // $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 - // - // Inspect Pod - // // --- + // summary: Inspect pod // produces: // - application/json // parameters: @@ -95,10 +88,9 @@ func (s *APIServer) registerPodsHandlers(r *mux.Router) error { // $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 - // - // Inspect Pod - // // --- + // summary: Pod exists + // description: Check if a pod exists by name or ID // produces: // - application/json // parameters: @@ -115,10 +107,8 @@ func (s *APIServer) registerPodsHandlers(r *mux.Router) error { // $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 - // - // Kill a pod - // // --- + // summary: Kill a pod // produces: // - application/json // parameters: @@ -143,10 +133,8 @@ func (s *APIServer) registerPodsHandlers(r *mux.Router) error { // $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 - // - // Pause a pod - // // --- + // summary: Pause a pod // produces: // - application/json // parameters: @@ -163,10 +151,8 @@ func (s *APIServer) registerPodsHandlers(r *mux.Router) error { // $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 - // - // Restart a pod - // // --- + // summary: Restart a pod // produces: // - application/json // parameters: @@ -183,10 +169,8 @@ func (s *APIServer) registerPodsHandlers(r *mux.Router) error { // $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 - // - // Start a pod - // // --- + // summary: Start a pod // produces: // - application/json // parameters: @@ -205,10 +189,8 @@ func (s *APIServer) registerPodsHandlers(r *mux.Router) error { // $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 - // - // Stop a pod - // // --- + // summary: Stop a pod // produces: // - application/json // parameters: @@ -233,10 +215,8 @@ func (s *APIServer) registerPodsHandlers(r *mux.Router) error { // $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 - // - // Unpause a pod - // // --- + // summary: Unpause a pod // produces: // - application/json // parameters: diff --git a/pkg/api/server/register_volumes.go b/pkg/api/server/register_volumes.go index 8fe5a67e4..34138cfbf 100644 --- a/pkg/api/server/register_volumes.go +++ b/pkg/api/server/register_volumes.go @@ -9,10 +9,8 @@ import ( func (s *APIServer) registerVolumeHandlers(r *mux.Router) error { // swagger:operation POST /libpod/volumes/create volumes createVolume - // - // Create a volume - // // --- + // summary: Create a volume // produces: // - application/json // responses: @@ -23,10 +21,8 @@ func (s *APIServer) registerVolumeHandlers(r *mux.Router) error { r.Handle("/libpod/volumes/create", APIHandler(s.Context, libpod.CreateVolume)).Methods(http.MethodPost) r.Handle("/libpod/volumes/json", APIHandler(s.Context, libpod.ListVolumes)).Methods(http.MethodGet) // swagger:operation POST /volumes/prune volumes pruneVolumes - // - // Prune volumes - // // --- + // summary: Prune volumes // produces: // - application/json // responses: @@ -36,10 +32,8 @@ func (s *APIServer) registerVolumeHandlers(r *mux.Router) error { // "$ref": "#/responses/InternalError" r.Handle("/libpod/volumes/prune", APIHandler(s.Context, libpod.PruneVolumes)).Methods(http.MethodPost) // swagger:operation GET /volumes/{nameOrID}/json volumes inspectVolume - // - // Inspect volume - // // --- + // summary: Inspect volume // parameters: // - in: path // name: nameOrID @@ -56,10 +50,8 @@ func (s *APIServer) registerVolumeHandlers(r *mux.Router) error { // "$ref": "#/responses/InternalError" r.Handle("/libpod/volumes/{name:..*}/json", APIHandler(s.Context, libpod.InspectVolume)).Methods(http.MethodGet) // swagger:operation DELETE /volumes/{nameOrID} volumes removeVolume - // - // Inspect volume - // // --- + // summary: Remove volume // parameters: // - in: path // name: nameOrID diff --git a/pkg/api/server/swagger.go b/pkg/api/server/swagger.go index 0eb57ebab..95129e637 100644 --- a/pkg/api/server/swagger.go +++ b/pkg/api/server/swagger.go @@ -131,3 +131,8 @@ type swagListContainers struct { //handlers.Container } } + +// To be determined +// swagger:response tbd +type swagTBD struct { +} |