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>

1 files changed, 120 insertions, 131 deletions

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