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>

2 files changed, 58 insertions, 7 deletions

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
 }