Swagger: fix inconsistencies (try #2)

As I've mentioned once or twice, hand-maintained swagger docs are evil. This commit attempts to fix: * Inconsistent methods (swagger says POST but code signature says GET) * Inconsistent capitalization * Typos ("Mounter", "pood") * Completely wrong paths (/inspect vs /json) * Missing .Method() registrations * Missing /libpod in some /volumes paths * Incorrect method declaration: /libpod/containers/.../kill was correct (POST) in swagger but wrong in the code itself (http.MethodGet). Correct the latter to MethodPost This is two hours' work, even with a script I have that tries to cross-check everything. Swagger docs should not be human-maintained. Signed-off-by: Ed Santiago <santiago@redhat.com>
2026-07-19 11:41:57 -04:00 · 2020-02-17 07:23:55 -07:00
parent a5d55966bd
commit 2a411bcbfa
7 changed files with 33 additions and 27 deletions
--- a/pkg/api/server/register_containers.go
+++ b/pkg/api/server/register_containers.go
@@ -10,7 +10,7 @@ import (
 )

 func (s *APIServer) registerContainersHandlers(r *mux.Router) error {
-	// swagger:operation POST /containers/create compat containerCreate
+	// swagger:operation POST /containers/create compat createContainer
 	// ---
 	//   summary: Create a container
 	//   tags:
@@ -172,7 +172,7 @@ func (s *APIServer) registerContainersHandlers(r *mux.Router) error {
 	//   500:
 	//     $ref: "#/responses/InternalError"
 	r.HandleFunc(VersionedPath("/containers/{name}/json"), s.APIHandler(generic.GetContainer)).Methods(http.MethodGet)
-	// swagger:operation post /containers/{name}/kill compat killcontainer
+	// swagger:operation POST /containers/{name}/kill compat killContainer
 	// ---
 	// tags:
 	//   - containers (compat)
@@ -202,7 +202,7 @@ func (s *APIServer) registerContainersHandlers(r *mux.Router) error {
 	//   500:
 	//     $ref: "#/responses/InternalError"
 	r.HandleFunc(VersionedPath("/containers/{name}/kill"), s.APIHandler(generic.KillContainer)).Methods(http.MethodPost)
-	// swagger:operation GET /containers/{name}/logs compat LogsFromContainer
+	// swagger:operation GET /containers/{name}/logs compat logsFromContainer
 	// ---
 	// tags:
 	//   - containers (compat)
@@ -458,7 +458,7 @@ func (s *APIServer) registerContainersHandlers(r *mux.Router) error {
 	//   500:
 	//     $ref: "#/responses/InternalError"
 	r.HandleFunc(VersionedPath("/containers/{name}/wait"), s.APIHandler(generic.WaitContainer)).Methods(http.MethodPost)
-	// swagger:operation POST /containers/{name}/attach compat attach
+	// swagger:operation POST /containers/{name}/attach compat attachContainer
 	// ---
 	// tags:
 	//   - containers (compat)
@@ -513,7 +513,7 @@ func (s *APIServer) registerContainersHandlers(r *mux.Router) error {
 	//   500:
 	//     $ref: "#/responses/InternalError"
 	r.HandleFunc(VersionedPath("/containers/{name}/attach"), s.APIHandler(handlers.AttachContainer)).Methods(http.MethodPost)
-	// swagger:operation POST /containers/{name}/resize compat resize
+	// swagger:operation POST /containers/{name}/resize compat resizeContainer
 	// ---
 	// tags:
 	//  - containers (compat)
@@ -638,7 +638,7 @@ func (s *APIServer) registerContainersHandlers(r *mux.Router) error {
 	//   500:
 	//     $ref: "#/responses/InternalError"
 	r.HandleFunc(VersionedPath("/libpod/containers/prune"), s.APIHandler(handlers.PruneContainers)).Methods(http.MethodPost)
-	// swagger:operation GET /libpod/containers/showmounted libpod showMounterContainers
+	// swagger:operation GET /libpod/containers/showmounted libpod showMountedContainers
 	// ---
 	// tags:
 	//  - containers
@@ -744,8 +744,8 @@ func (s *APIServer) registerContainersHandlers(r *mux.Router) error {
 	//     $ref: "#/responses/ConflictError"
 	//   500:
 	//     $ref: "#/responses/InternalError"
-	r.HandleFunc(VersionedPath("/libpod/containers/{name}/kill"), s.APIHandler(libpod.KillContainer)).Methods(http.MethodGet)
-	// swagger:operation GET /libpod/containers/{name}/mount libpod mountContainer
+	r.HandleFunc(VersionedPath("/libpod/containers/{name}/kill"), s.APIHandler(libpod.KillContainer)).Methods(http.MethodPost)
+	// swagger:operation POST /libpod/containers/{name}/mount libpod mountContainer
 	// ---
 	// tags:
 	//  - containers
@@ -1023,7 +1023,7 @@ func (s *APIServer) registerContainersHandlers(r *mux.Router) error {
 	//   500:
 	//     $ref: "#/responses/InternalError"
 	r.HandleFunc(VersionedPath("/libpod/containers/{name}/wait"), s.APIHandler(libpod.WaitContainer)).Methods(http.MethodPost)
-	// swagger:operation POST /libpod/containers/{name}/exists libpod containerExists
+	// swagger:operation GET /libpod/containers/{name}/exists libpod containerExists
 	// ---
 	// tags:
 	//  - containers
--- a/pkg/api/server/register_events.go
+++ b/pkg/api/server/register_events.go
@@ -1,6 +1,8 @@
 package server

 import (
+	"net/http"
+
 	"github.com/containers/libpod/pkg/api/handlers"
 	"github.com/gorilla/mux"
 )
@@ -32,6 +34,6 @@ func (s *APIServer) registerEventsHandlers(r *mux.Router) error {
 	//     description: returns a string of json data describing an event
 	//   500:
 	//     "$ref": "#/responses/InternalError"
-	r.Handle(VersionedPath("/events"), s.APIHandler(handlers.GetEvents))
+	r.Handle(VersionedPath("/events"), s.APIHandler(handlers.GetEvents)).Methods(http.MethodGet)
 	return nil
 }
--- a/pkg/api/server/register_exec.go
+++ b/pkg/api/server/register_exec.go
@@ -142,7 +142,7 @@ func (s *APIServer) registerExecHandlers(r *mux.Router) error {
 	//   500:
 	//     $ref: "#/responses/InternalError"
 	r.Handle(VersionedPath("/exec/{id}/resize"), s.APIHandler(handlers.ResizeExec)).Methods(http.MethodPost)
-	// swagger:operation GET /exec/{id}/inspect compat inspectExec
+	// swagger:operation GET /exec/{id}/json compat inspectExec
 	// ---
 	// tags:
 	//   - exec (compat)
@@ -303,7 +303,7 @@ func (s *APIServer) registerExecHandlers(r *mux.Router) error {
 	//   500:
 	//     $ref: "#/responses/InternalError"
 	r.Handle(VersionedPath("/libpod/exec/{id}/resize"), s.APIHandler(handlers.ResizeExec)).Methods(http.MethodPost)
-	// swagger:operation GET /libpod/exec/{id}/inspect libpod libpodInspectExec
+	// swagger:operation GET /libpod/exec/{id}/json libpod libpodInspectExec
 	// ---
 	// tags:
 	//   - exec
--- a/pkg/api/server/register_images.go
+++ b/pkg/api/server/register_images.go
@@ -264,7 +264,7 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
 	//     $ref: "#/responses/NoSuchImage"
 	//   500:
 	//     $ref: "#/responses/InternalError"
-	r.Handle(VersionedPath("/images/{name:.*}/json"), s.APIHandler(generic.GetImage))
+	r.Handle(VersionedPath("/images/{name:.*}/json"), s.APIHandler(generic.GetImage)).Methods(http.MethodGet)
 	// swagger:operation POST /images/{name:.*}/tag compat tagImage
 	// ---
 	// tags:
@@ -299,7 +299,7 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
 	//   500:
 	//     $ref: '#/responses/InternalError'
 	r.Handle(VersionedPath("/images/{name:.*}/tag"), s.APIHandler(handlers.TagImage)).Methods(http.MethodPost)
-	// swagger:operation POST /commit/ compat commitContainer
+	// swagger:operation POST /commit compat commitContainer
 	// ---
 	// tags:
 	//  - containers (compat)
@@ -345,7 +345,7 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
 	//     $ref: '#/responses/InternalError'
 	r.Handle(VersionedPath("/commit"), s.APIHandler(generic.CommitContainer)).Methods(http.MethodPost)

-	// swagger:operation POST /build images buildImage
+	// swagger:operation POST /build compat buildImage
 	// ---
 	// tags:
 	//  - images
@@ -558,7 +558,7 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
 		libpod endpoints
 	*/

-	// swagger:operation POST /libpod/images/{name:.*}/exists libpod libpodImageExists
+	// swagger:operation GET /libpod/images/{name:.*}/exists libpod libpodImageExists
 	// ---
 	// tags:
 	//  - images
@@ -579,8 +579,8 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
 	//     $ref: '#/responses/NoSuchImage'
 	//   500:
 	//     $ref: '#/responses/InternalError'
-	r.Handle(VersionedPath("/libpod/images/{name:.*}/exists"), s.APIHandler(libpod.ImageExists))
-	// swagger:operation POST /libpod/images/{name:.*}/tree libpod libpodImageTree
+	r.Handle(VersionedPath("/libpod/images/{name:.*}/exists"), s.APIHandler(libpod.ImageExists)).Methods(http.MethodGet)
+	// swagger:operation GET /libpod/images/{name:.*}/tree libpod libpodImageTree
 	// ---
 	// tags:
 	//  - images
@@ -605,7 +605,7 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
 	//     $ref: '#/responses/NoSuchImage'
 	//   500:
 	//     $ref: '#/responses/InternalError'
-	r.Handle(VersionedPath("/libpod/images/{name:.*}/tree"), s.APIHandler(libpod.ImageTree))
+	r.Handle(VersionedPath("/libpod/images/{name:.*}/tree"), s.APIHandler(libpod.ImageTree)).Methods(http.MethodGet)
 	// swagger:operation GET /libpod/images/{name:.*}/history libpod libpodImageHistory
 	// ---
 	// tags:
@@ -852,7 +852,7 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
 	//   500:
 	//     $ref: '#/responses/InternalError'
 	r.Handle(VersionedPath("/libpod/images/{name:.*}"), s.APIHandler(handlers.RemoveImage)).Methods(http.MethodDelete)
-	// swagger:operation GET /libpod/images/{name:.*}/get libpod libpoodExportImage
+	// swagger:operation GET /libpod/images/{name:.*}/get libpod libpodExportImage
 	// ---
 	// tags:
 	//  - images
@@ -906,7 +906,7 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
 	//     $ref: '#/responses/NoSuchImage'
 	//   500:
 	//     $ref: '#/responses/InternalError'
-	r.Handle(VersionedPath("/libpod/images/{name:.*}/json"), s.APIHandler(libpod.GetImage))
+	r.Handle(VersionedPath("/libpod/images/{name:.*}/json"), s.APIHandler(libpod.GetImage)).Methods(http.MethodGet)
 	// swagger:operation POST /libpod/images/{name:.*}/tag libpod libpodTagImage
 	// ---
 	// tags:
--- a/pkg/api/server/register_system.go
+++ b/pkg/api/server/register_system.go
@@ -1,11 +1,13 @@
 package server

 import (
+	"net/http"
+
 	"github.com/containers/libpod/pkg/api/handlers/generic"
 	"github.com/gorilla/mux"
 )

 func (s *APIServer) registerSystemHandlers(r *mux.Router) error {
-	r.Handle(VersionedPath("/system/df"), s.APIHandler(generic.GetDiskUsage))
+	r.Handle(VersionedPath("/system/df"), s.APIHandler(generic.GetDiskUsage)).Methods(http.MethodGet)
 	return nil
 }
--- a/pkg/api/server/register_version.go
+++ b/pkg/api/server/register_version.go
@@ -1,12 +1,14 @@
 package server

 import (
+	"net/http"
+
 	"github.com/containers/libpod/pkg/api/handlers"
 	"github.com/gorilla/mux"
 )

 func (s *APIServer) registerVersionHandlers(r *mux.Router) error {
-	r.Handle("/version", s.APIHandler(handlers.VersionHandler))
-	r.Handle(VersionedPath("/version"), s.APIHandler(handlers.VersionHandler))
+	r.Handle("/version", s.APIHandler(handlers.VersionHandler)).Methods(http.MethodGet)
+	r.Handle(VersionedPath("/version"), s.APIHandler(handlers.VersionHandler)).Methods(http.MethodGet)
 	return nil
 }
--- a/pkg/api/server/register_volumes.go
+++ b/pkg/api/server/register_volumes.go
@@ -20,7 +20,7 @@ func (s *APIServer) registerVolumeHandlers(r *mux.Router) error {
 	//      "$ref": "#/responses/InternalError"
 	r.Handle("/libpod/volumes/create", s.APIHandler(libpod.CreateVolume)).Methods(http.MethodPost)
 	r.Handle("/libpod/volumes/json", s.APIHandler(libpod.ListVolumes)).Methods(http.MethodGet)
-	// swagger:operation POST /volumes/prune volumes pruneVolumes
+	// swagger:operation POST /libpod/volumes/prune volumes pruneVolumes
 	// ---
 	// summary: Prune volumes
 	// produces:
@@ -31,7 +31,7 @@ func (s *APIServer) registerVolumeHandlers(r *mux.Router) error {
 	//   '500':
 	//      "$ref": "#/responses/InternalError"
 	r.Handle("/libpod/volumes/prune", s.APIHandler(libpod.PruneVolumes)).Methods(http.MethodPost)
-	// swagger:operation GET /volumes/{name}/json volumes inspectVolume
+	// swagger:operation GET /libpod/volumes/{name}/json volumes inspectVolume
 	// ---
 	// summary: Inspect volume
 	// parameters:
@@ -50,7 +50,7 @@ func (s *APIServer) registerVolumeHandlers(r *mux.Router) error {
 	//   '500':
 	//      "$ref": "#/responses/InternalError"
 	r.Handle("/libpod/volumes/{name}/json", s.APIHandler(libpod.InspectVolume)).Methods(http.MethodGet)
-	// swagger:operation DELETE /volumes/{name} volumes removeVolume
+	// swagger:operation DELETE /libpod/volumes/{name} volumes removeVolume
 	// ---
 	// summary: Remove volume
 	// parameters: