[CI:DOCS]update apiv2 documentation with swagger goods

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

10 files changed, 733 insertions, 479 deletions

diff --git a/Makefile b/Makefile
index cbbcbf9e6..c1ae33cfe 100644
--- a/Makefile
+++ b/Makefile
@@ -153,7 +153,7 @@ lint: .gopathok varlink_generate ## Execute the source code linter
 	@./.tool/lint
 
 golangci-lint: .gopathok varlink_generate .install.golangci-lint
-	$(GOBIN)/golangci-lint run --tests=false
+	$(GOBIN)/golangci-lint run --tests=false --skip-files swagger.go
 
 gofmt: ## Verify the source code gofmt
 	find . -name '*.go' ! -path './vendor/*' -exec gofmt -s -w {} \+
diff --git a/pkg/api/handlers/libpod/pods.go b/pkg/api/handlers/libpod/pods.go
index cde1fcd48..daaf9d018 100644
--- a/pkg/api/handlers/libpod/pods.go
+++ b/pkg/api/handlers/libpod/pods.go
@@ -137,9 +137,6 @@ func Pods(w http.ResponseWriter, r *http.Request) {
 }
 
 func PodInspect(w http.ResponseWriter, r *http.Request) {
-	// 200 ok
-	// 404 no such
-	// 500 internal
 	runtime := r.Context().Value("runtime").(*libpod.Runtime)
 	name := mux.Vars(r)["name"]
 	pod, err := runtime.LookupPod(name)
@@ -222,10 +219,6 @@ func PodStop(w http.ResponseWriter, r *http.Request) {
 }
 
 func PodStart(w http.ResponseWriter, r *http.Request) {
-	// 200 ok
-	// 304 no modified
-	// 404 no such
-	// 500 internal
 	runtime := r.Context().Value("runtime").(*libpod.Runtime)
 	allContainersRunning := true
 	name := mux.Vars(r)["name"]
@@ -267,9 +260,6 @@ func PodStart(w http.ResponseWriter, r *http.Request) {
 }
 
 func PodDelete(w http.ResponseWriter, r *http.Request) {
-	// 200
-	// 404 no such
-	// 500 internal
 	var (
 		runtime = r.Context().Value("runtime").(*libpod.Runtime)
 		decoder = r.Context().Value("decoder").(*schema.Decoder)
@@ -295,13 +285,10 @@ func PodDelete(w http.ResponseWriter, r *http.Request) {
 		utils.Error(w, "Something went wrong", http.StatusInternalServerError, err)
 		return
 	}
-	utils.WriteResponse(w, http.StatusOK, "")
+	utils.WriteResponse(w, http.StatusNoContent, "")
 }
 
 func PodRestart(w http.ResponseWriter, r *http.Request) {
-	// 200 ok
-	// 404 no such
-	// 500 internal
 	runtime := r.Context().Value("runtime").(*libpod.Runtime)
 	name := mux.Vars(r)["name"]
 	pod, err := runtime.LookupPod(name)
@@ -318,8 +305,6 @@ func PodRestart(w http.ResponseWriter, r *http.Request) {
 }
 
 func PodPrune(w http.ResponseWriter, r *http.Request) {
-	// 200 ok
-	// 500 internal
 	var (
 		err     error
 		pods    []*libpod.Pod
@@ -357,13 +342,10 @@ func PodPrune(w http.ResponseWriter, r *http.Request) {
 			return
 		}
 	}
-	utils.WriteResponse(w, http.StatusOK, "")
+	utils.WriteResponse(w, http.StatusNoContent, "")
 }
 
 func PodPause(w http.ResponseWriter, r *http.Request) {
-	// 200 ok
-	// 404 no such
-	// 500 internal
 	runtime := r.Context().Value("runtime").(*libpod.Runtime)
 	name := mux.Vars(r)["name"]
 	pod, err := runtime.LookupPod(name)
@@ -376,7 +358,7 @@ func PodPause(w http.ResponseWriter, r *http.Request) {
 		utils.Error(w, "Something went wrong", http.StatusInternalServerError, err)
 		return
 	}
-	utils.WriteResponse(w, http.StatusOK, "")
+	utils.WriteResponse(w, http.StatusNoContent, "")
 }
 
 func PodUnpause(w http.ResponseWriter, r *http.Request) {
@@ -399,10 +381,6 @@ func PodUnpause(w http.ResponseWriter, r *http.Request) {
 }
 
 func PodKill(w http.ResponseWriter, r *http.Request) {
-	// 200 ok
-	// 404 no such
-	// 409 has conflict
-	// 500 internal
 	var (
 		runtime = r.Context().Value("runtime").(*libpod.Runtime)
 		decoder = r.Context().Value("decoder").(*schema.Decoder)
@@ -451,9 +429,6 @@ func PodKill(w http.ResponseWriter, r *http.Request) {
 }
 
 func PodExists(w http.ResponseWriter, r *http.Request) {
-	// 200 ok
-	// 404 no such
-	// 500 internal (needs work)
 	runtime := r.Context().Value("runtime").(*libpod.Runtime)
 	name := mux.Vars(r)["name"]
 	_, err := runtime.LookupPod(name)
diff --git a/pkg/api/handlers/libpod/volumes.go b/pkg/api/handlers/libpod/volumes.go
index ece59a4b6..3e0e597c6 100644
--- a/pkg/api/handlers/libpod/volumes.go
+++ b/pkg/api/handlers/libpod/volumes.go
@@ -63,23 +63,9 @@ func CreateVolume(w http.ResponseWriter, r *http.Request) {
 }
 
 func InspectVolume(w http.ResponseWriter, r *http.Request) {
-	// 200 ok
-	// 404 no such
-	// 500 internal
 	var (
 		runtime = r.Context().Value("runtime").(*libpod.Runtime)
-		decoder = r.Context().Value("decoder").(*schema.Decoder)
 	)
-	query := struct {
-	}{
-		// override any golang type defaults
-	}
-
-	if err := decoder.Decode(&query, r.URL.Query()); err != nil {
-		utils.Error(w, http.StatusText(http.StatusBadRequest), http.StatusBadRequest,
-			errors.Wrapf(err, "Failed to parse parameters for %s", r.URL.String()))
-		return
-	}
 	name := mux.Vars(r)["name"]
 	vol, err := runtime.GetVolume(name)
 	if err != nil {
@@ -115,22 +101,9 @@ func ListVolumes(w http.ResponseWriter, r *http.Request) {
 }
 
 func PruneVolumes(w http.ResponseWriter, r *http.Request) {
-	// 200 ok
-	// 500 internal
 	var (
 		runtime = r.Context().Value("runtime").(*libpod.Runtime)
-		decoder = r.Context().Value("decoder").(*schema.Decoder)
 	)
-	query := struct {
-	}{
-		// override any golang type defaults
-	}
-
-	if err := decoder.Decode(&query, r.URL.Query()); err != nil {
-		utils.Error(w, http.StatusText(http.StatusBadRequest), http.StatusBadRequest,
-			errors.Wrapf(err, "Failed to parse parameters for %s", r.URL.String()))
-		return
-	}
 	pruned, errs := runtime.PruneVolumes(r.Context())
 	if errs != nil {
 		if len(errs) > 1 {
@@ -144,9 +117,6 @@ func PruneVolumes(w http.ResponseWriter, r *http.Request) {
 }
 
 func RemoveVolume(w http.ResponseWriter, r *http.Request) {
-	// 200 ok
-	// 404 no such
-	// 500 internal
 	var (
 		runtime = r.Context().Value("runtime").(*libpod.Runtime)
 		decoder = r.Context().Value("decoder").(*schema.Decoder)
@@ -170,5 +140,5 @@ func RemoveVolume(w http.ResponseWriter, r *http.Request) {
 	if err := runtime.RemoveVolume(r.Context(), vol, query.Force); err != nil {
 		utils.InternalServerError(w, err)
 	}
-	utils.WriteResponse(w, http.StatusOK, "")
+	utils.WriteResponse(w, http.StatusNoContent, "")
 }
diff --git a/pkg/api/handlers/swagger.go b/pkg/api/handlers/swagger.go
new file mode 100644
index 000000000..b677a5a0b
--- /dev/null
+++ b/pkg/api/handlers/swagger.go
@@ -0,0 +1,126 @@
+package handlers
+
+import (
+	"github.com/containers/libpod/cmd/podman/shared"
+	"github.com/containers/libpod/libpod"
+	"github.com/containers/libpod/libpod/image"
+	"github.com/containers/libpod/pkg/inspect"
+	"github.com/docker/docker/api/types"
+)
+
+// History response
+// swagger:response DocsHistory
+type swagHistory struct {
+	// in:body
+	Body struct {
+		HistoryResponse
+	}
+}
+
+// Inspect response
+// swagger:response DocsImageInspect
+type swagImageInspect struct {
+	// in:body
+	Body struct {
+		ImageInspect
+	}
+}
+
+// Delete response
+// swagger:response DocsImageDeleteResponse
+type swagImageDeleteResponse struct {
+	// in:body
+	Body struct {
+		image.ImageDeleteResponse
+	}
+}
+
+// Search results
+// swagger:response DocsSearchResponse
+type swagSearchResponse struct {
+	// in:body
+	Body struct {
+		image.SearchResult
+	}
+}
+
+// Inspect image
+// swagger:response DocsLibpodInspectImageResponse
+type swagLibpodInspectImageResponse struct {
+	// in:body
+	Body struct {
+		inspect.ImageData
+	}
+}
+
+// Prune containers
+// swagger:response DocsContainerPruneReport
+type swagContainerPruneReport struct {
+	// in: body
+	Body struct {
+		ContainersPruneReport
+	}
+}
+
+// Inspect container
+// swagger:response DocsContainerInspectResponse
+type swagContainerInspectResponse struct {
+	// in:body
+	Body struct {
+		types.ContainerJSON
+	}
+}
+
+// List processes in container
+// swagger:response DockerTopResponse
+type swagDockerTopResponse struct {
+	// in:body
+	Body struct {
+		ContainerTopOKBody
+	}
+}
+
+// List containers
+// swagger:response LibpodListContainersResponse
+type swagLibpodListContainersResponse struct {
+	// in:body
+	Body struct {
+		shared.PsContainerOutput
+	}
+}
+
+// Inspect container
+// swagger:response LibpodInspectContainerResponse
+type swagLibpodInspectContainerResponse struct {
+	// in:body
+	Body struct {
+		libpod.InspectContainerData
+	}
+}
+
+// List pods
+// swagger:response ListPodsResponse
+type swagListPodsResponse struct {
+	// in:body
+	Body struct {
+		libpod.PodInspect
+	}
+}
+
+// Inspect pod
+// swagger:response InspectPodResponse
+type swagInspectPodResponse struct {
+	// in:body
+	Body struct {
+		libpod.PodInspect
+	}
+}
+
+// Inspect volume
+// swagger:response InspectVolumeResponse
+type swagInspectVolumeResponse struct {
+	// in:body
+	Body struct {
+		libpod.InspectVolumeData
+	}
+}
diff --git a/pkg/api/handlers/utils/errors.go b/pkg/api/handlers/utils/errors.go
index 69d4e40f8..3ec0742bd 100644
--- a/pkg/api/handlers/utils/errors.go
+++ b/pkg/api/handlers/utils/errors.go
@@ -2,9 +2,9 @@ package utils
 
 import (
 	"fmt"
-	"github.com/containers/libpod/libpod/define"
 	"net/http"
 
+	"github.com/containers/libpod/libpod/define"
 	"github.com/pkg/errors"
 	log "github.com/sirupsen/logrus"
 )
@@ -73,7 +73,9 @@ func BadRequest(w http.ResponseWriter, key string, value string, err error) {
 }
 
 type ErrorModel struct {
+	// root cause
 	Because string `json:"cause"`
+	// error message
 	Message string `json:"message"`
 }
 
diff --git a/pkg/api/server/register_containers.go b/pkg/api/server/register_containers.go
index 7d80f2f67..af1881624 100644
--- a/pkg/api/server/register_containers.go
+++ b/pkg/api/server/register_containers.go
@@ -24,25 +24,15 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
 	//    description: container name
 	// responses:
 	//   '201':
-	//     schema:
-	//     items:
-	//       "$ref": "#/ctrCreateResponse"
+	//    description: tbd
 	//   '400':
-	//     description: bad parameter
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/BadParamError"
 	//   '404':
-	//     description: no such container
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/NoSuchContainer"
 	//   '409':
-	//     description: conflict
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/types/ConflictError"
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      "$ref": "#/types/InternalError"
 	r.HandleFunc(VersionedPath("/containers/create"), APIHandler(s.Context, generic.CreateContainer)).Methods(http.MethodPost)
 	// swagger:operation GET /containers/json containers listContainers
 	//
@@ -56,15 +46,11 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
 	//     schema:
 	//     type: array
 	//     items:
-	//       "$ref": "#/types/Container"
+	//       "$ref": "#/responses/Container"
 	//   '400':
-	//     description: bad parameter
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/BadParamError"
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      "$ref": "#/responses/InternalError"
 	r.HandleFunc(VersionedPath("/containers/json"), APIHandler(s.Context, generic.ListContainers)).Methods(http.MethodGet)
 	// swagger:operation POST  /containers/prune containers pruneContainers
 	//
@@ -80,12 +66,9 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
 	// - application/json
 	// responses:
 	//   '200':
-	//     schema:
-	//       "$ref": "#/types/ContainerPruneReport"
+	//       "$ref": "#/responses/DocsContainerPruneReport"
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      "$ref": "#/responses/InternalError"
 	r.HandleFunc(VersionedPath("/containers/prune"), APIHandler(s.Context, generic.PruneContainers)).Methods(http.MethodPost)
 	// swagger:operation DELETE /containers/{nameOrID} containers removeContainer
 	//
@@ -112,27 +95,16 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
 	// produces:
 	// - application/json
 	// responses:
-	//   '200':
-	//     schema:
-	//     type: array
-	//     items:
-	//       "$ref": "#/types/Container"
+	//   '204':
+	//     description: no error
 	//   '400':
-	//     description: bad parameter
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/BadParamError"
 	//   '404':
-	//     description: no such container
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/NoSuchContainer"
 	//   '409':
-	//     description: conflict
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/ConflictError"
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      "$ref": "#/responses/InternalError"
 	r.HandleFunc(VersionedPath("/containers/{name:..*}"), APIHandler(s.Context, generic.RemoveContainer)).Methods(http.MethodDelete)
 	// swagger:operation GET /containers/{nameOrID}/json containers getContainer
 	//
@@ -148,17 +120,11 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
 	// - application/json
 	// responses:
 	//   '200':
-	//     schema:
-	//     items:
-	//       "$ref": "#/types/ContainerJSON"
+	//      "$ref": "#/responses/DocsContainerInspectResponse"
 	//   '404':
-	//     description: no such container
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//     "$ref": "#/responses/NoSuchContainer"
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//     "$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
 	//
@@ -179,19 +145,12 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
 	// responses:
 	//   '204':
 	//     description: no error
-	//     schema:
 	//   '404':
-	//     description: no such container
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/NoSuchContainer"
 	//   '409':
-	//     description: conflict
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/ConflictError"
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      "$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
 	//
@@ -235,16 +194,11 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
 	// - application/json
 	// responses:
 	//   '200':
-	//     description: no error
-	//     schema:
+	//     description: tbd
 	//   '404':
-	//     description: no such container
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//      "$ref": "#/responses/NoSuchContainer"
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      "$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
 	//
@@ -261,15 +215,10 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
 	// responses:
 	//   '204':
 	//     description: no error
-	//     schema:
 	//   '404':
-	//     description: no such container
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/NoSuchContainer"
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      "$ref": "#/responses/InternalError"
 	r.HandleFunc(VersionedPath("/containers/{name:..*}/pause"), APIHandler(s.Context, handlers.PauseContainer)).Methods(http.MethodPost)
 	r.HandleFunc(VersionedPath("/containers/{name:..*}/rename"), APIHandler(s.Context, handlers.UnsupportedHandler)).Methods(http.MethodPost)
 	// swagger:operation POST /containers/{nameOrID}/restart containers restartContainer
@@ -291,15 +240,10 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
 	// responses:
 	//   '204':
 	//     description: no error
-	//     schema:
 	//   '404':
-	//     description: no such container
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/NoSuchContainer"
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      "$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
 	//
@@ -321,21 +265,15 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
 	//   '204':
 	//     description: no error
 	//   '304':
-	//     description: container already started
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/ContainerAlreadyStartedError"
 	//   '404':
-	//     description: no such container
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/NoSuchContainer"
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      "$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 contrainer
+	//  Get stats for a container
 	//
 	// ---
 	// parameters:
@@ -350,22 +288,14 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
 	// produces:
 	// - application/json
 	// responses:
-	//   '200':
-	//     description: no error
-	//     schema:
-	//       "ref": "#/handler/stats"
+	//   '204':
+	//     description: tbd
 	//   '304':
-	//     description: container already started
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/ContainerAlreadyStartedError"
 	//   '404':
-	//     description: no such container
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/NoSuchContainer"
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      "$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
 	//
@@ -387,17 +317,11 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
 	//   '204':
 	//     description: no error
 	//   '304':
-	//     description: container already stopped
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/ContainerAlreadyStoppedError"
 	//   '404':
-	//     description: no such container
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/NoSuchContainer"
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      "$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
 	//
@@ -417,17 +341,11 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
 	// - application/json
 	// responses:
 	//   '200':
-	//     description: no error
-	//     schema:
-	//       "ref": "#/types/ContainerTopBody"
+	//       "ref": "#/responses/DockerTopResponse"
 	//   '404':
-	//     description: no such container
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/NoSuchContainer"
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      "$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
 	//
@@ -446,13 +364,9 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
 	//     description: no error
 	//     schema:
 	//   '404':
-	//     description: no such container
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/NoSuchContainer"
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      "$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
 	//
@@ -473,15 +387,10 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
 	// responses:
 	//   '204':
 	//     description: no error
-	//     schema:
 	//   '404':
-	//     description: no such container
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/NoSuchContainer"
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      "$ref": "#/responses/InternalError"
 	r.HandleFunc(VersionedPath("/containers/{name:..*}/wait"), APIHandler(s.Context, generic.WaitContainer)).Methods(http.MethodPost)
 
 	/*
@@ -501,15 +410,11 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
 	//     schema:
 	//     type: array
 	//     items:
-	//       "$ref": "#/shared/GetPsContainerOutput"
+	//       "$ref": "#/responses/LibpodListContainersResponse"
 	//   '400':
-	//     description: bad parameter
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/BadParamError"
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      "$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
 	//
@@ -529,12 +434,9 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
 	// - application/json
 	// responses:
 	//   '200':
-	//     schema:
-	//       "$ref": "#/types/ContainerPruneReport"
+	//     description: TBD
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      "$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
 	//
@@ -545,12 +447,13 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
 	// - application/json
 	// responses:
 	//   '200':
+	//     description: mounted containers
 	//     schema:
-	//       "$ref": "TBD"
+	//      type: object
+	//      additionalProperties:
+	//       type: string
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      "$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
 	//
@@ -573,27 +476,16 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
 	// produces:
 	// - application/json
 	// responses:
-	//   '200':
-	//     schema:
-	//     type: array
-	//     items:
-	//       "$ref": "#/types/Container"
+	//   '204':
+	//     description: no error
 	//   '400':
-	//     description: bad parameter
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/BadParamError"
 	//   '404':
-	//     description: no such container
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/NoSuchContainer"
 	//   '409':
-	//     description: conflict
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/ConflictError"
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      "$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
 	//
@@ -613,17 +505,11 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
 	// - application/json
 	// responses:
 	//   '200':
-	//     schema:
-	//     items:
-	//       "$ref": "#InspectContainerData"
+	//       "$ref": "#/responses/LibpodInspectContainerResponse"
 	//   '404':
-	//     description: no such container
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/NoSuchContainer"
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      "$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
 	//
@@ -645,19 +531,12 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
 	// responses:
 	//   '204':
 	//     description: no error
-	//     schema:
 	//   '404':
-	//     description: no such container
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/NoSuchContainer"
 	//   '409':
-	//     description: conflict
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/ConflictError"
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      "$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
 	//
@@ -673,18 +552,16 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
 	// - application/json
 	// responses:
 	//   '200':
+	//     description: mounted container
 	//     schema:
-	//     items:
-	//       "$ref": "string"
+	//      description: id
+	//      type: string
+	//      example: 3c784de79b791b4ebd3ac55e511f97fedc042328499554937a3f8bfd9c1a2cb8
 	//   '404':
-	//     description: no such container
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/NoSuchContainer"
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
-	r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/mount"), APIHandler(s.Context, libpod.LogsFromContainer)).Methods(http.MethodPost)
+	//      "$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
 	//
@@ -701,15 +578,10 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
 	// responses:
 	//   '204':
 	//     description: no error
-	//     schema:
 	//   '404':
-	//     description: no such container
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/NoSuchContainer"
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      "$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
 	//
@@ -730,15 +602,10 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
 	// responses:
 	//   '204':
 	//     description: no error
-	//     schema:
 	//   '404':
-	//     description: no such container
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/NoSuchContainer"
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      "$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
 	//
@@ -760,17 +627,11 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
 	//   '204':
 	//     description: no error
 	//   '304':
-	//     description: container already started
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/ContainerAlreadyStartedError"
 	//   '404':
-	//     description: no such container
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/NoSuchContainer"
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      "$ref": "#/responses/InternalError"
 	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)
@@ -789,15 +650,10 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
 	// responses:
 	//   '204':
 	//     description: no error
-	//     schema:
 	//   '404':
-	//     description: no such container
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/NoSuchContainer"
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      "$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
 	//
@@ -818,15 +674,10 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
 	// responses:
 	//   '204':
 	//     description: no error
-	//     schema:
 	//   '404':
-	//     description: no such container
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/NoSuchContainer"
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      "$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
 	//
@@ -842,16 +693,11 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
 	// - application/json
 	// responses:
 	//   '204':
-	//     description: no error
-	//     schema:
+	//     description: container exists
 	//   '404':
-	//     description: no such container
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/NoSuchContainer"
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      "$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
 	//
@@ -873,17 +719,11 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
 	//   '204':
 	//     description: no error
 	//   '304':
-	//     description: container already stopped
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/ContainerAlreadyStoppedError"
 	//   '404':
-	//     description: no such container
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       "$ref": "#/responses/NoSuchContainer"
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      "$ref": "#/responses/InternalError"
 	r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/stop"), APIHandler(s.Context, handlers.StopContainer)).Methods(http.MethodPost)
 	return nil
 }
diff --git a/pkg/api/server/register_images.go b/pkg/api/server/register_images.go
index 4ad4409df..488427f3c 100644
--- a/pkg/api/server/register_images.go
+++ b/pkg/api/server/register_images.go
@@ -30,15 +30,15 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
 	//   '200':
 	//     schema:
 	//     items:
-	//       "$ref": "TBD"
+	//       $ref: "TBD"
 	//   '404':
 	//     description: repo or image does not exist
 	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       $ref: "#/responses/generalError"
 	//   '500':
 	//     description: unexpected error
 	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      $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
 	//
@@ -60,15 +60,15 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
 	//   '200':
 	//     schema:
 	//     items:
-	//       "$ref": "TBD"
+	//       $ref: "TBD"
 	//   '404':
 	//     description: repo or image does not exist
 	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       $ref: "#/responses/generalError"
 	//   '500':
 	//     description: unexpected error
 	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      $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
 	//
@@ -79,13 +79,13 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
 	// - application/json
 	// responses:
 	//   '200':
-	//     schema:
-	//     items:
-	//       "$ref": "#/types/ImageSummary"
+	//      schema:
+	//        type: array
+	//        items:
+	//          schema:
+	//           $ref: "#/responses/DockerImageSummary"
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      $ref: '#/responses/InternalError'
 	r.Handle(VersionedPath("/images/json"), APIHandler(s.Context, generic.GetImages)).Methods(http.MethodGet)
 	// swagger:operation POST /images/load images loadImage
 	//
@@ -101,13 +101,9 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
 	// - application/json
 	// responses:
 	//   '200':
-	//     schema:
-	//     items:
-	//       "$ref": "#/types/ImageSummary"
+	//     description: TBD
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      $ref: '#/responses/InternalError'
 	r.Handle(VersionedPath("/images/load"), APIHandler(s.Context, handlers.LoadImage)).Methods(http.MethodPost)
 	// swagger:operation POST /images/prune images pruneImages
 	//
@@ -125,11 +121,9 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
 	//   '200':
 	//     schema:
 	//     items:
-	//       "$ref": "#/ImageDeleteResponse"
+	//       $ref: "#/responses/DocsImageDeleteResponse"
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      $ref: '#/responses/InternalError'
 	r.Handle(VersionedPath("/images/prune"), APIHandler(s.Context, generic.PruneImages)).Methods(http.MethodPost)
 	// swagger:operation GET /images/search images searchImages
 	//
@@ -153,14 +147,9 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
 	// - application/json
 	// responses:
 	//   '200':
-	//     schema:
-	//     items:
-	//       "$ref": "#/images.SearchResult"
-	//     description: no error
+	//       $ref: "#/responses/DocsSearchResponse"
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      $ref: '#/responses/InternalError'
 	r.Handle(VersionedPath("/images/search"), APIHandler(s.Context, handlers.SearchImages)).Methods(http.MethodGet)
 	// swagger:operation DELETE /images/{nameOrID} images removeImage
 	//
@@ -177,25 +166,16 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
 	//    type: bool
 	//    description: not supported
 	// produces:
-	// - application/json
+	//  - application/json
 	// responses:
 	//   '200':
-	//     schema:
-	//     items:
-	//       "$ref": "TBD"
-	//     description: no error
+	//       $ref: "#/responses/DocsImageDeleteResponse"
 	//   '404':
-	//     description: no such image
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       $ref: '#/responses/BadParamError'
 	//   '409':
-	//     description: conflict
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       $ref: '#/responses/ConflictError'
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      $ref: '#/responses/InternalError'
 	r.Handle(VersionedPath("/images/{name:..*}"), APIHandler(s.Context, handlers.RemoveImage)).Methods(http.MethodDelete)
 	// swagger:operation GET /images/{nameOrID}/get images exportImage
 	//
@@ -208,17 +188,14 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
 	//    required: true
 	//    description: the name or ID of the container
 	// produces:
-	// - application/json
+	//  - application/json
 	// responses:
 	//   '200':
 	//     schema:
-	//     items:
-	//       "$ref": "TBD"
-	//     description: no error
+	//       $ref: "TBD"
+	//     description: TBD
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      $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
 	//
@@ -234,17 +211,11 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
 	// - application/json
 	// responses:
 	//   '200':
-	//     schema:
-	//     items:
-	//       "$ref": "#/types/HistoryResponse"
+	//     $ref: "#/responses/DocsHistory"
 	//   '404':
-	//     description: no such image
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//     $ref: "#/responses/NoSuchImage"
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//     $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
 	//
@@ -260,17 +231,11 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
 	// - application/json
 	// responses:
 	//   '200':
-	//     schema:
-	//     items:
-	//       "$ref": "#/types/imageInspect"
+	//       $ref: "#/responses/DocsImageInspect"
 	//   '404':
-	//     description: no such image
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       $ref: "#/responses/NoSuchImage"
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      $ref: "#/responses/InternalError"
 	r.Handle(VersionedPath("/images/{name:..*}/json"), APIHandler(s.Context, generic.GetImage))
 	// swagger:operation POST /images/{nameOrID}/tag images tagImage
 	//
@@ -293,24 +258,16 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
 	// produces:
 	// - application/json
 	// responses:
-	//   '201':
+	//   201:
 	//     description: no error
-	//   '400':
-	//     description: bad parameter
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
-	//   '404':
-	//     description: no such image
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
-	//   '409':
-	//     description: conflict
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
-	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//   400:
+	//     $ref: '#/responses/BadParamError'
+	//   404:
+	//     $ref: '#/responses/NoSuchImage'
+	//   409:
+	//     $ref: '#/responses/ConflictError'
+	//   500:
+	//     $ref: '#/responses/InternalError'
 	r.Handle(VersionedPath("/images/{name:..*}/tag"), APIHandler(s.Context, handlers.TagImage)).Methods(http.MethodPost)
 	// swagger:operation POST /commit/ commit commitContainer
 	//
@@ -352,13 +309,9 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
 	//   '201':
 	//     description: no error
 	//   '404':
-	//     description: no such image
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//      $ref: '#/responses/NoSuchImage'
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      $ref: '#/responses/InternalError'
 	r.Handle(VersionedPath("/commit"), APIHandler(s.Context, generic.CommitContainer)).Methods(http.MethodPost)
 
 	/*
@@ -390,13 +343,9 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
 	//   '204':
 	//     description: image exists
 	//   '404':
-	//     description: no such image
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       $ref: '#/responses/NoSuchImage'
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      $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
@@ -415,15 +364,11 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
 	//   '200':
 	//     schema:
 	//     items:
-	//       "$ref": "#/types/HistoryResponse"
+	//       $ref: "#/responses/HistoryResponse"
 	//   '404':
-	//     description: no such image
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       $ref: '#/responses/NoSuchImage'
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      $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
 	//
@@ -436,11 +381,9 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
 	//   '200':
 	//     schema:
 	//     items:
-	//       "$ref": "#/types/ImageSummary"
+	//       $ref: "#/responses/DockerImageSummary"
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      $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
 	//
@@ -456,13 +399,9 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
 	// - application/json
 	// responses:
 	//   '200':
-	//     schema:
-	//     items:
-	//       "$ref": "#/types/ImageSummary"
+	//     description: TBD
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//     $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
 	//
@@ -484,11 +423,9 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
 	//   '200':
 	//     schema:
 	//     items:
-	//       "$ref": "#/ImageDeleteResponse"
+	//       $ref: "#/responses/DocsImageDeleteResponse"
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      $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
 	//
@@ -514,12 +451,9 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
 	//   '200':
 	//     schema:
 	//     items:
-	//       "$ref": "#/images.SearchResult"
-	//     description: no error
+	//       $ref: "#/responses/DocsSearchResponse"
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      $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
 	//
@@ -541,20 +475,13 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
 	//   '200':
 	//     schema:
 	//     items:
-	//       "$ref": "TBD"
-	//     description: no error
+	//       $ref: "#/responses/DocsIageDeleteResponse"
 	//   '404':
-	//     description: no such image
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       $ref: '#/responses/NoSuchImage'
 	//   '409':
-	//     description: conflict
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       $ref: '#/responses/ConflictError'
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      $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
 	//
@@ -578,18 +505,11 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
 	// - application/json
 	// responses:
 	//   '200':
-	//     schema:
-	//     items:
-	//       "$ref": "TBD"
-	//     description: no error
+	//     description: TBD
 	//   '404':
-	//     description: no such image
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       $ref: '#/responses/NoSuchImage'
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      $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
 	//
@@ -607,15 +527,11 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
 	//   '200':
 	//     schema:
 	//     items:
-	//       "$ref": "#/inspect/ImageData"
+	//       $ref: "#/responses/DocsLibpodInspectImageResponse"
 	//   '404':
-	//     description: no such image
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       $ref: '#/responses/NoSuchImage'
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      $ref: '#/responses/InternalError'
 	r.Handle(VersionedPath("/libpod/images/{name:..*}/json"), APIHandler(s.Context, libpod.GetImage))
 	// swagger:operation POST /libpod/images/{nameOrID}/tag images tagImage
 	//
@@ -641,21 +557,13 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
 	//   '201':
 	//     description: no error
 	//   '400':
-	//     description: bad parameter
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       $ref: '#/responses/BadParamError'
 	//   '404':
-	//     description: no such image
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       $ref: '#/responses/NoSuchImage'
 	//   '409':
-	//     description: conflict
-	//     schema:
-	//       "$ref": "#/types/ErrorModel"
+	//       $ref: '#/responses/ConflictError'
 	//   '500':
-	//     description: unexpected error
-	//     schema:
-	//      "$ref": "#/types/ErrorModel"
+	//      $ref: '#/responses/InternalError'
 	r.Handle(VersionedPath("/libpod/images/{name:..*}/tag"), APIHandler(s.Context, handlers.TagImage)).Methods(http.MethodPost)
 
 	r.Handle(VersionedPath("/build"), APIHandler(s.Context, handlers.BuildImage)).Methods(http.MethodPost)
diff --git a/pkg/api/server/register_pods.go b/pkg/api/server/register_pods.go
index b5915da98..c2e10277e 100644
--- a/pkg/api/server/register_pods.go
+++ b/pkg/api/server/register_pods.go
@@ -8,17 +8,249 @@ import (
 )
 
 func (s *APIServer) registerPodsHandlers(r *mux.Router) error {
+	// swagger:operation GET /libpod/pods/json pods ListPods
+	//
+	// List Pods
+	//
+	// ---
+	// produces:
+	// - application/json
+	// parameters:
+	// - in: query
+	//   name: filters
+	//   descriptions: needs description and plumbing for filters
+	// responses:
+	//   '200':
+	//      $ref: "#/responses/ListPodsResponse"
+	//   '400':
+	//      $ref: "#/responses/BadParamError"
+	//   '500':
+	//      $ref: "#responses/InternalError"
 	r.Handle(VersionedPath("/libpod/pods/json"), APIHandler(s.Context, libpod.Pods)).Methods(http.MethodGet)
 	r.Handle(VersionedPath("/libpod/pods/create"), APIHandler(s.Context, libpod.PodCreate)).Methods(http.MethodPost)
+	// swagger:operation POST /libpod/pods/prune pods PrunePods
+	//
+	// Prune unused pods
+	//
+	// ---
+	// parameters:
+	//  - in: query
+	//    name: force
+	//    description: force delete
+	//    type: bool
+	// produces:
+	// - application/json
+	// responses:
+	//   '204':
+	//      description: no error
+	//   '400':
+	//      $ref: "#/responses/BadParamError"
+	//   '500':
+	//      $ref: "#responses/InternalError"
 	r.Handle(VersionedPath("/libpod/pods/prune"), APIHandler(s.Context, libpod.PodPrune)).Methods(http.MethodPost)
+	// swagger:operation DELETE /libpod/pods/{nameOrID} pods removePod
+	//
+	// Remove Pod
+	//
+	// ---
+	// produces:
+	// - application/json
+	// parameters:
+	//  - in: path
+	//    name: nameOrID
+	//    required: true
+	//    description: the name or ID of the pod
+	//  - in: query
+	//    name: force
+	//    type: bool
+	//    description: force delete
+	// responses:
+	//   '204':
+	//      description: no error
+	//   '400':
+	//      $ref: "#/responses/BadParamError"
+	//   '404':
+	//      $ref: "#/responses/NoSuchPod"
+	//   '500':
+	//      $ref: "#responses/InternalError"
 	r.Handle(VersionedPath("/libpod/pods/{name:..*}"), APIHandler(s.Context, libpod.PodDelete)).Methods(http.MethodDelete)
-	r.Handle(VersionedPath("/libpod/pods/{name:..*}"), APIHandler(s.Context, libpod.PodInspect)).Methods(http.MethodGet)
+	// swagger:operation GET /libpod/pods/{nameOrID}/json pods inspectPod
+	//
+	// Inspect Pod
+	//
+	// ---
+	// produces:
+	// - application/json
+	// parameters:
+	//  - in: path
+	//    name: nameOrID
+	//    required: true
+	//    description: the name or ID of the pod
+	// responses:
+	//   '200':
+	//      $ref: "#/responses/InspectPodResponse"
+	//   '404':
+	//      $ref: "#/responses/NoSuchPod"
+	//   '500':
+	//      $ref: "#responses/InternalError"
+	r.Handle(VersionedPath("/libpod/pods/{name:..*}/json"), APIHandler(s.Context, libpod.PodInspect)).Methods(http.MethodGet)
+	// swagger:operation GET /libpod/pods/{nameOrID}/exists pods podExists
+	//
+	// Inspect Pod
+	//
+	// ---
+	// produces:
+	// - application/json
+	// parameters:
+	//  - in: path
+	//    name: nameOrID
+	//    required: true
+	//    description: the name or ID of the pod
+	// responses:
+	//   '204':
+	//      description: pod exists
+	//   '404':
+	//      $ref: "#/responses/NoSuchPod"
+	//   '500':
+	//      $ref: "#responses/InternalError"
 	r.Handle(VersionedPath("/libpod/pods/{name:..*}/exists"), APIHandler(s.Context, libpod.PodExists)).Methods(http.MethodGet)
+	// swagger:operation POST /libpod/pods/{nameOrID}/kill pods killPod
+	//
+	// Kill a pod
+	//
+	// ---
+	// produces:
+	// - application/json
+	// parameters:
+	//  - in: path
+	//    name: nameOrID
+	//    required: true
+	//    description: the name or ID of the pod
+	//  - in: query
+	//    name: signal
+	//    type: int
+	//    description: signal to be sent to pod
+	// responses:
+	//   '204':
+	//      description: no error
+	//   '400':
+	//      $ref: "#/responses/BadParamError"
+	//   '404':
+	//      $ref: "#/responses/NoSuchPod"
+	//   '409':
+	//      $ref: "#/responses/ConflictError"
+	//   '500':
+	//      $ref: "#responses/InternalError"
 	r.Handle(VersionedPath("/libpod/pods/{name:..*}/kill"), APIHandler(s.Context, libpod.PodKill)).Methods(http.MethodPost)
+	// swagger:operation POST /libpod/pods/{nameOrID}/pause pods pausePod
+	//
+	// Pause a pod
+	//
+	// ---
+	// produces:
+	// - application/json
+	// parameters:
+	//  - in: path
+	//    name: nameOrID
+	//    required: true
+	//    description: the name or ID of the pod
+	// responses:
+	//   '204':
+	//      description: no error
+	//   '404':
+	//      $ref: "#/responses/NoSuchPod"
+	//   '500':
+	//      $ref: "#responses/InternalError"
 	r.Handle(VersionedPath("/libpod/pods/{name:..*}/pause"), APIHandler(s.Context, libpod.PodPause)).Methods(http.MethodPost)
+	// swagger:operation POST /libpod/pods/{nameOrID}/restart pods restartPod
+	//
+	// Restart a pod
+	//
+	// ---
+	// produces:
+	// - application/json
+	// parameters:
+	//  - in: path
+	//    name: nameOrID
+	//    required: true
+	//    description: the name or ID of the pod
+	// responses:
+	//   '204':
+	//      description: no error
+	//   '404':
+	//      $ref: "#/responses/NoSuchPod"
+	//   '500':
+	//      $ref: "#responses/InternalError"
 	r.Handle(VersionedPath("/libpod/pods/{name:..*}/restart"), APIHandler(s.Context, libpod.PodRestart)).Methods(http.MethodPost)
+	// swagger:operation POST /libpod/pods/{nameOrID}/start pods startPod
+	//
+	// Start a pod
+	//
+	// ---
+	// produces:
+	// - application/json
+	// parameters:
+	//  - in: path
+	//    name: nameOrID
+	//    required: true
+	//    description: the name or ID of the pod
+	// responses:
+	//   '204':
+	//      description: no error
+	//   '304':
+	//      $ref: "#/responses/PodAlreadyStartedError"
+	//   '404':
+	//      $ref: "#/responses/NoSuchPod"
+	//   '500':
+	//      $ref: "#responses/InternalError"
 	r.Handle(VersionedPath("/libpod/pods/{name:..*}/start"), APIHandler(s.Context, libpod.PodStart)).Methods(http.MethodPost)
+	// swagger:operation POST /libpod/pods/{nameOrID}/stop pods stopPod
+	//
+	// Stop a pod
+	//
+	// ---
+	// produces:
+	// - application/json
+	// parameters:
+	//  - in: path
+	//    name: nameOrID
+	//    required: true
+	//    description: the name or ID of the pod
+	//  - in: query
+	//    name: t
+	//    type: int
+	//    description: timeout
+	// responses:
+	//   '204':
+	//      description: no error
+	//   '304':
+	//      $ref: "#/responses/PodAlreadyStoppedError"
+	//   '400':
+	//      $ref: "#/responses/BadParamError"
+	//   '404':
+	//      $ref: "#/responses/NoSuchPod"
+	//   '500':
+	//      $ref: "#responses/InternalError"
 	r.Handle(VersionedPath("/libpod/pods/{name:..*}/stop"), APIHandler(s.Context, libpod.PodStop)).Methods(http.MethodPost)
+	// swagger:operation POST /libpod/pods/{nameOrID}/unpause pods unpausePod
+	//
+	// Unpause a pod
+	//
+	// ---
+	// produces:
+	// - application/json
+	// parameters:
+	//  - in: path
+	//    name: nameOrID
+	//    required: true
+	//    description: the name or ID of the pod
+	// responses:
+	//   '204':
+	//      description: no error
+	//   '404':
+	//      $ref: "#/responses/NoSuchPod"
+	//   '500':
+	//      $ref: "#responses/InternalError"
 	r.Handle(VersionedPath("/libpod/pods/{name:..*}/unpause"), APIHandler(s.Context, libpod.PodUnpause)).Methods(http.MethodPost)
 	return nil
 }
diff --git a/pkg/api/server/register_volumes.go b/pkg/api/server/register_volumes.go
index 3a9cf8c2d..8fe5a67e4 100644
--- a/pkg/api/server/register_volumes.go
+++ b/pkg/api/server/register_volumes.go
@@ -8,10 +8,78 @@ import (
 )
 
 func (s *APIServer) registerVolumeHandlers(r *mux.Router) error {
+	// swagger:operation POST /libpod/volumes/create volumes createVolume
+	//
+	//  Create a volume
+	//
+	// ---
+	// produces:
+	// - application/json
+	// responses:
+	//   '200':
+	//     description: tbd
+	//   '500':
+	//      "$ref": "#/responses/InternalError"
 	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
+	//
+	// ---
+	// produces:
+	// - application/json
+	// responses:
+	//   '204':
+	//     description: no error
+	//   '500':
+	//      "$ref": "#/responses/InternalError"
 	r.Handle("/libpod/volumes/prune", APIHandler(s.Context, libpod.PruneVolumes)).Methods(http.MethodPost)
+	// swagger:operation GET /volumes/{nameOrID}/json volumes inspectVolume
+	//
+	//  Inspect volume
+	//
+	// ---
+	// parameters:
+	//  - in: path
+	//    name: nameOrID
+	//    required: true
+	//    description: the name or ID of the volume
+	// produces:
+	// - application/json
+	// responses:
+	//   '200':
+	//       "$ref": "#/responses/InspectVolumeResponse"
+	//   '404':
+	//       "$ref": "#/responses/NoSuchVolume"
+	//   '500':
+	//      "$ref": "#/responses/InternalError"
 	r.Handle("/libpod/volumes/{name:..*}/json", APIHandler(s.Context, libpod.InspectVolume)).Methods(http.MethodGet)
+	// swagger:operation DELETE /volumes/{nameOrID} volumes removeVolume
+	//
+	//  Inspect volume
+	//
+	// ---
+	// parameters:
+	//  - in: path
+	//    name: nameOrID
+	//    required: true
+	//    description: the name or ID of the volume
+	//  - in: query
+	//    name: force
+	//    type: bool
+	//    description: force removal
+	// produces:
+	// - application/json
+	// responses:
+	//   '204':
+	//       description: no error
+	//   '400':
+	//       "$ref": "#/responses/BadParamError"
+	//   '404':
+	//       "$ref": "#/responses/NoSuchVolume"
+	//   '500':
+	//      "$ref": "#/responses/InternalError"
 	r.Handle("/libpod/volumes/{name:..*}", APIHandler(s.Context, libpod.RemoveVolume)).Methods(http.MethodDelete)
 	return nil
 }
diff --git a/pkg/api/server/swagger.go b/pkg/api/server/swagger.go
new file mode 100644
index 000000000..0eb57ebab
--- /dev/null
+++ b/pkg/api/server/swagger.go
@@ -0,0 +1,133 @@
+package server
+
+import (
+	"github.com/containers/libpod/pkg/api/handlers"
+	"github.com/containers/libpod/pkg/api/handlers/utils"
+)
+
+// No such image
+// swagger:response NoSuchImage
+type swagErrNoSuchImage struct {
+	// in:body
+	Body struct {
+		utils.ErrorModel
+	}
+}
+
+// No such container
+// swagger:response NoSuchContainer
+type swagErrNoSuchContainer struct {
+	// in:body
+	Body struct {
+		utils.ErrorModel
+	}
+}
+
+// No such volume
+// swagger:response NoSuchVolume
+type swagErrNoSuchVolume struct {
+	// in:body
+	Body struct {
+		utils.ErrorModel
+	}
+}
+
+// No such pod
+// swagger:response NoSuchPod
+type swagErrNoSuchPod struct {
+	// in:body
+	Body struct {
+		utils.ErrorModel
+	}
+}
+
+// Internal error
+// swagger:response InternalError
+type swagInternalError struct {
+	// in:body
+	Body struct {
+		utils.ErrorModel
+	}
+}
+
+// Generic error
+// swagger:response GenericError
+type swagGenericError struct {
+	// in:body
+	Body struct {
+		utils.ErrorModel
+	}
+}
+
+// Conflict error
+// swagger:response ConflictError
+type swagConflictError struct {
+	// in:body
+	Body struct {
+		utils.ErrorModel
+	}
+}
+
+// Bad parameter
+// swagger:response BadParamError
+type swagBadParamError struct {
+	// in:body
+	Body struct {
+		utils.ErrorModel
+	}
+}
+
+// Container already started
+// swagger:response ContainerAlreadyStartedError
+type swagContainerAlreadyStartedError struct {
+	// in:body
+	Body struct {
+		utils.ErrorModel
+	}
+}
+
+// Container already stopped
+// swagger:response ContainerAlreadyStoppedError
+type swagContainerAlreadyStopped struct {
+	// in:body
+	Body struct {
+		utils.ErrorModel
+	}
+}
+
+// Pod already started
+// swagger:response PodAlreadyStartedError
+type swagPodAlreadyStartedError struct {
+	// in:body
+	Body struct {
+		utils.ErrorModel
+	}
+}
+
+// Pod already stopped
+// swagger:response PodAlreadyStoppedError
+type swagPodAlreadyStopped struct {
+	// in:body
+	Body struct {
+		utils.ErrorModel
+	}
+}
+
+// Image summary
+// swagger:response DockerImageSummary
+type swagImageSummary struct {
+	// in:body
+	Body struct {
+		handlers.ImageSummary
+	}
+}
+
+// List Containers
+// swagger:response DocsListContainer
+type swagListContainers struct {
+	// in:body
+	Body struct {
+		// This causes go-swagger to crash
+		//handlers.Container
+	}
+}