swagger documentation updates

adhere closer to the spec by using description and summary fields and
also ensuring that the id is unique to avoid collision between generic
and libpod endpoints.

also, make swagger output work with redoc which seems to display our
information better for our needs.

Signed-off-by: baude <bbaude@redhat.com>

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 {
+}