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>

6 files changed, 92 insertions, 38 deletions

diff --git a/pkg/api/handlers/generic/ping.go b/pkg/api/handlers/generic/ping.go
deleted file mode 100644
index 00afd86bc..000000000
--- a/pkg/api/handlers/generic/ping.go
+++ /dev/null
@@ -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)
-}
diff --git a/pkg/api/handlers/ping.go b/pkg/api/handlers/ping.go
new file mode 100644
index 000000000..d41da60f3
--- /dev/null
+++ b/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")
+}
diff --git a/pkg/api/handlers/types.go b/pkg/api/handlers/types.go
index 9c8562744..34b428852 100644
--- a/pkg/api/handlers/types.go
+++ b/pkg/api/handlers/types.go
@@ -70,10 +70,6 @@ type ContainerStats struct {
 	docker.ContainerStats
 }
 
-type Ping struct {
-	docker.Ping
-}
-
 type Version struct {
 	docker.Version
 }
diff --git a/pkg/api/server/register_images.go b/pkg/api/server/register_images.go
index f1cc0574c..18a90dc3d 100644
--- a/pkg/api/server/register_images.go
+++ b/pkg/api/server/register_images.go
@@ -300,8 +300,9 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
 	// swagger:operation POST /commit/ compat commitContainer
 	// ---
 	// tags:
-	//  - commit (compat)
-	// summary: Create a new image from a container
+	//  - containers (compat)
+	// summary: New Image
+	// description: Create a new image from a container
 	// parameters:
 	//  - in: query
 	//    name: container
diff --git a/pkg/api/server/register_ping.go b/pkg/api/server/register_ping.go
index 4956f9822..086e674a1 100644
--- a/pkg/api/server/register_ping.go
+++ b/pkg/api/server/register_ping.go
@@ -3,15 +3,65 @@ package server
 import (
 	"net/http"
 
-	"github.com/containers/libpod/pkg/api/handlers/generic"
+	"github.com/containers/libpod/pkg/api/handlers"
 	"github.com/gorilla/mux"
 )
 
 func (s *APIServer) registerPingHandlers(r *mux.Router) error {
-	r.Handle("/_ping", APIHandler(s.Context, generic.PingGET)).Methods(http.MethodGet)
-	r.Handle("/_ping", APIHandler(s.Context, generic.PingHEAD)).Methods("HEAD")
 
-	// libpod
-	r.Handle("/libpod/_ping", APIHandler(s.Context, generic.PingGET)).Methods(http.MethodGet)
+	r.Handle("/_ping", APIHandler(s.Context, handlers.Ping)).Methods(http.MethodGet)
+	r.Handle("/_ping", APIHandler(s.Context, handlers.Ping)).Methods(http.MethodHead)
+
+	// swagger:operation GET /libpod/_ping libpod libpodPingGet
+	// ---
+	//   summary: Ping service
+	//   description: |
+	//     Return protocol information in response headers.
+	//     `HEAD /libpod/_ping` is also supported.
+	//     `/_ping` is available for compatibility with other engines.
+	//   tags:
+	//   - system (compat)
+	//   - system
+	//   produces:
+	//   - text/plain
+	//   responses:
+	//     200:
+	//       description: Success
+	//       schema:
+	//         description: OK
+	//         type: string
+	//         example: "OK"
+	//       headers:
+	//         API-Version:
+	//           type: string
+	//           description: Max compatibility API Version the server supports
+	//         BuildKit-Version:
+	//           type: string
+	//           description: Default version of docker image builder
+	//         Docker-Experimental:
+	//           type: boolean
+	//           description: If the server is running with experimental mode enabled, always true
+	//         Cache-Control:
+	//           type: string
+	//           description: always no-cache
+	//         Pragma:
+	//           type: string
+	//           description: always no-cache
+	//         Libpod-API-Version:
+	//           type: string
+	//           description: |
+	//             Max Podman API Version the server supports.
+	//             Available if service is backed by Podman, therefore may be used to
+	//             determine if talking to Podman engine or another engine
+	//         Libpod-Buildha-Version:
+	//           type: string
+	//           description: |
+	//             Default version of libpod image builder.
+	//               Available if service is backed by Podman, therefore may be used to
+	//               determine if talking to Podman engine or another engine
+	//     500:
+	//       $ref: "#/responses/InternalError"
+	r.Handle("/libpod/_ping", APIHandler(s.Context, handlers.Ping)).Methods(http.MethodGet)
+	r.Handle("/libpod/_ping", APIHandler(s.Context, handlers.Ping)).Methods(http.MethodHead)
 	return nil
 }
diff --git a/pkg/api/tags.yaml b/pkg/api/tags.yaml
index ad0de656f..be70fb3d8 100644
--- a/pkg/api/tags.yaml
+++ b/pkg/api/tags.yaml
@@ -7,7 +7,11 @@ tags:
       description: Actions related to pods
     - name: volumes
       description: Actions related to volumes
+    - name: system
+      description: Actions related to Podman engine
     - name: containers (compat)
       description: Actions related to containers for the compatibility endpoints
     - name: images (compat)
       description: Actions related to images for the compatibility endpoints
+    - name: system (compat)
+      description: Actions related to Podman and compatiblity engines