Update /_ping support

* Add swagger support and documentation
* Promote handler as there can only ever be one
* Update swagger tags

Between verbs and paths there are four endpoints for /_ping.  I've
attempted to document them well without four copies of the details.
Time will tell.

Clients will use the headers `Libpod-API-Version` and
`Libpod-Buildha-Version` to determine if they are connecting to a Podman
service or some other compatible engine.

Client calls GET(/_ping):
 * VARLINK engines will fail with error message
 * Compatible engines will return 200 without Libpod headers
 * Podman engines will return 200 and Libpod headers

Signed-off-by: Jhon Honce <jhonce@redhat.com>

pkg/api/handlers/generic/ping.go

@@ -1,27 +0,0 @@
-package generic
-
-import (
-	"fmt"
-	"net/http"
-
-	"github.com/containers/libpod/pkg/api/handlers"
-)
-
-func PingGET(w http.ResponseWriter, _ *http.Request) {
-	setHeaders(w)
-	fmt.Fprintln(w, "OK")
-}
-
-func PingHEAD(w http.ResponseWriter, _ *http.Request) {
-	setHeaders(w)
-	fmt.Fprintln(w, "")
-}
-
-func setHeaders(w http.ResponseWriter) {
-	w.Header().Set("API-Version", handlers.DefaultApiVersion)
-	w.Header().Set("BuildKit-Version", "")
-	w.Header().Set("Docker-Experimental", "true")
-	w.Header().Set("Cache-Control", "no-cache")
-	w.Header().Set("Pragma", "no-cache")
-	w.WriteHeader(http.StatusOK)
-}

pkg/api/handlers/ping.go

@@ -0,0 +1,30 @@
+package handlers
+
+import (
+	"fmt"
+	"net/http"
+
+	"github.com/containers/buildah"
+)
+
+// Ping returns headers to client about the service
+//
+// This handler must always be the same for the compatibility and libpod URL trees!
+// Clients will use the Header availability to test which backend engine is in use.
+func Ping(w http.ResponseWriter, r *http.Request) {
+	w.Header().Set("API-Version", DefaultApiVersion)
+	w.Header().Set("BuildKit-Version", "")
+	w.Header().Set("Docker-Experimental", "true")
+	w.Header().Set("Cache-Control", "no-cache")
+	w.Header().Set("Pragma", "no-cache")
+
+	// API-Version and Libpod-API-Version may not always be equal
+	w.Header().Set("Libpod-API-Version", DefaultApiVersion)
+	w.Header().Set("Libpod-Buildha-Version", buildah.Version)
+	w.WriteHeader(http.StatusOK)
+
+	if r.Method == http.MethodGet {
+		fmt.Fprint(w, "OK")
+	}
+	fmt.Fprint(w, "\n")
+}

pkg/api/handlers/types.go

@@ -70,10 +70,6 @@ type ContainerStats struct {
 	docker.ContainerStats
 }
 
-type Ping struct {
-	docker.Ping
-}
-
 type Version struct {
 	docker.Version
 }