From 2a411bcbfa3dc72d3a8cb35c2d1004ab05e4e0e8 Mon Sep 17 00:00:00 2001 From: Ed Santiago Date: Mon, 17 Feb 2020 07:23:55 -0700 Subject: 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 --- pkg/api/server/register_containers.go | 18 +++++++++--------- pkg/api/server/register_events.go | 4 +++- pkg/api/server/register_exec.go | 4 ++-- pkg/api/server/register_images.go | 18 +++++++++--------- pkg/api/server/register_system.go | 4 +++- pkg/api/server/register_version.go | 6 ++++-- pkg/api/server/register_volumes.go | 6 +++--- 7 files changed, 33 insertions(+), 27 deletions(-) diff --git a/pkg/api/server/register_containers.go b/pkg/api/server/register_containers.go index 39e5dd10b..06877863c 100644 --- 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 diff --git a/pkg/api/server/register_events.go b/pkg/api/server/register_events.go index a511725b2..bc3b62662 100644 --- 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 } diff --git a/pkg/api/server/register_exec.go b/pkg/api/server/register_exec.go index 581f6f79a..ad62de3f5 100644 --- 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 diff --git a/pkg/api/server/register_images.go b/pkg/api/server/register_images.go index 923a1f266..5b9ac7952 100644 --- 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: diff --git a/pkg/api/server/register_system.go b/pkg/api/server/register_system.go index 73f0fb470..188c1cdac 100644 --- 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 } diff --git a/pkg/api/server/register_version.go b/pkg/api/server/register_version.go index c8f9dcede..ee01ad4b3 100644 --- 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 } diff --git a/pkg/api/server/register_volumes.go b/pkg/api/server/register_volumes.go index 1ccf92b46..efe56a3ad 100644 --- 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: -- cgit v1.2.3-54-g00ecf