Skip to content

Commit 2a411bc

Browse files
edsantiagoedsantiago
committed
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>
1 parent a5d5596 commit 2a411bc

File tree

7 files changed

+33
-27
lines changed

7 files changed

+33
-27
lines changed

‎pkg/api/server/register_containers.go‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ import (
1010
)
1111

1212
func (s *APIServer) registerContainersHandlers(r *mux.Router) error {
13-
// swagger:operation POST /containers/create compat containerCreate
13+
// swagger:operation POST /containers/create compat createContainer
1414
// ---
1515
// summary: Create a container
1616
// tags:
@@ -172,7 +172,7 @@ func (s *APIServer) registerContainersHandlers(r *mux.Router) error {
172172
// 500:
173173
// $ref: "#/responses/InternalError"
174174
r.HandleFunc(VersionedPath("/containers/{name}/json"), s.APIHandler(generic.GetContainer)).Methods(http.MethodGet)
175-
// swagger:operation post /containers/{name}/kill compat killcontainer
175+
// swagger:operation POST /containers/{name}/kill compat killContainer
176176
// ---
177177
// tags:
178178
// - containers (compat)
@@ -202,7 +202,7 @@ func (s *APIServer) registerContainersHandlers(r *mux.Router) error {
202202
// 500:
203203
// $ref: "#/responses/InternalError"
204204
r.HandleFunc(VersionedPath("/containers/{name}/kill"), s.APIHandler(generic.KillContainer)).Methods(http.MethodPost)
205-
// swagger:operation GET /containers/{name}/logs compat LogsFromContainer
205+
// swagger:operation GET /containers/{name}/logs compat logsFromContainer
206206
// ---
207207
// tags:
208208
// - containers (compat)
@@ -458,7 +458,7 @@ func (s *APIServer) registerContainersHandlers(r *mux.Router) error {
458458
// 500:
459459
// $ref: "#/responses/InternalError"
460460
r.HandleFunc(VersionedPath("/containers/{name}/wait"), s.APIHandler(generic.WaitContainer)).Methods(http.MethodPost)
461-
// swagger:operation POST /containers/{name}/attach compat attach
461+
// swagger:operation POST /containers/{name}/attach compat attachContainer
462462
// ---
463463
// tags:
464464
// - containers (compat)
@@ -513,7 +513,7 @@ func (s *APIServer) registerContainersHandlers(r *mux.Router) error {
513513
// 500:
514514
// $ref: "#/responses/InternalError"
515515
r.HandleFunc(VersionedPath("/containers/{name}/attach"), s.APIHandler(handlers.AttachContainer)).Methods(http.MethodPost)
516-
// swagger:operation POST /containers/{name}/resize compat resize
516+
// swagger:operation POST /containers/{name}/resize compat resizeContainer
517517
// ---
518518
// tags:
519519
// - containers (compat)
@@ -638,7 +638,7 @@ func (s *APIServer) registerContainersHandlers(r *mux.Router) error {
638638
// 500:
639639
// $ref: "#/responses/InternalError"
640640
r.HandleFunc(VersionedPath("/libpod/containers/prune"), s.APIHandler(handlers.PruneContainers)).Methods(http.MethodPost)
641-
// swagger:operation GET /libpod/containers/showmounted libpod showMounterContainers
641+
// swagger:operation GET /libpod/containers/showmounted libpod showMountedContainers
642642
// ---
643643
// tags:
644644
// - containers
@@ -744,8 +744,8 @@ func (s *APIServer) registerContainersHandlers(r *mux.Router) error {
744744
// $ref: "#/responses/ConflictError"
745745
// 500:
746746
// $ref: "#/responses/InternalError"
747-
r.HandleFunc(VersionedPath("/libpod/containers/{name}/kill"), s.APIHandler(libpod.KillContainer)).Methods(http.MethodGet)
748-
// swagger:operation GET /libpod/containers/{name}/mount libpod mountContainer
747+
r.HandleFunc(VersionedPath("/libpod/containers/{name}/kill"), s.APIHandler(libpod.KillContainer)).Methods(http.MethodPost)
748+
// swagger:operation POST /libpod/containers/{name}/mount libpod mountContainer
749749
// ---
750750
// tags:
751751
// - containers
@@ -1023,7 +1023,7 @@ func (s *APIServer) registerContainersHandlers(r *mux.Router) error {
10231023
// 500:
10241024
// $ref: "#/responses/InternalError"
10251025
r.HandleFunc(VersionedPath("/libpod/containers/{name}/wait"), s.APIHandler(libpod.WaitContainer)).Methods(http.MethodPost)
1026-
// swagger:operation POST /libpod/containers/{name}/exists libpod containerExists
1026+
// swagger:operation GET /libpod/containers/{name}/exists libpod containerExists
10271027
// ---
10281028
// tags:
10291029
// - containers

‎pkg/api/server/register_events.go‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
package server
22

33
import (
4+
"net/http"
5+
46
"github.com/containers/libpod/pkg/api/handlers"
57
"github.com/gorilla/mux"
68
)
@@ -32,6 +34,6 @@ func (s *APIServer) registerEventsHandlers(r *mux.Router) error {
3234
// description: returns a string of json data describing an event
3335
// 500:
3436
// "$ref": "#/responses/InternalError"
35-
r.Handle(VersionedPath("/events"), s.APIHandler(handlers.GetEvents))
37+
r.Handle(VersionedPath("/events"), s.APIHandler(handlers.GetEvents)).Methods(http.MethodGet)
3638
return nil
3739
}

‎pkg/api/server/register_exec.go‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -142,7 +142,7 @@ func (s *APIServer) registerExecHandlers(r *mux.Router) error {
142142
// 500:
143143
// $ref: "#/responses/InternalError"
144144
r.Handle(VersionedPath("/exec/{id}/resize"), s.APIHandler(handlers.ResizeExec)).Methods(http.MethodPost)
145-
// swagger:operation GET /exec/{id}/inspect compat inspectExec
145+
// swagger:operation GET /exec/{id}/json compat inspectExec
146146
// ---
147147
// tags:
148148
// - exec (compat)
@@ -303,7 +303,7 @@ func (s *APIServer) registerExecHandlers(r *mux.Router) error {
303303
// 500:
304304
// $ref: "#/responses/InternalError"
305305
r.Handle(VersionedPath("/libpod/exec/{id}/resize"), s.APIHandler(handlers.ResizeExec)).Methods(http.MethodPost)
306-
// swagger:operation GET /libpod/exec/{id}/inspect libpod libpodInspectExec
306+
// swagger:operation GET /libpod/exec/{id}/json libpod libpodInspectExec
307307
// ---
308308
// tags:
309309
// - exec

‎pkg/api/server/register_images.go‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -264,7 +264,7 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
264264
// $ref: "#/responses/NoSuchImage"
265265
// 500:
266266
// $ref: "#/responses/InternalError"
267-
r.Handle(VersionedPath("/images/{name:.*}/json"), s.APIHandler(generic.GetImage))
267+
r.Handle(VersionedPath("/images/{name:.*}/json"), s.APIHandler(generic.GetImage)).Methods(http.MethodGet)
268268
// swagger:operation POST /images/{name:.*}/tag compat tagImage
269269
// ---
270270
// tags:
@@ -299,7 +299,7 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
299299
// 500:
300300
// $ref: '#/responses/InternalError'
301301
r.Handle(VersionedPath("/images/{name:.*}/tag"), s.APIHandler(handlers.TagImage)).Methods(http.MethodPost)
302-
// swagger:operation POST /commit/ compat commitContainer
302+
// swagger:operation POST /commit compat commitContainer
303303
// ---
304304
// tags:
305305
// - containers (compat)
@@ -345,7 +345,7 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
345345
// $ref: '#/responses/InternalError'
346346
r.Handle(VersionedPath("/commit"), s.APIHandler(generic.CommitContainer)).Methods(http.MethodPost)
347347

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

561-
// swagger:operation POST /libpod/images/{name:.*}/exists libpod libpodImageExists
561+
// swagger:operation GET /libpod/images/{name:.*}/exists libpod libpodImageExists
562562
// ---
563563
// tags:
564564
// - images
@@ -579,8 +579,8 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
579579
// $ref: '#/responses/NoSuchImage'
580580
// 500:
581581
// $ref: '#/responses/InternalError'
582-
r.Handle(VersionedPath("/libpod/images/{name:.*}/exists"), s.APIHandler(libpod.ImageExists))
583-
// swagger:operation POST /libpod/images/{name:.*}/tree libpod libpodImageTree
582+
r.Handle(VersionedPath("/libpod/images/{name:.*}/exists"), s.APIHandler(libpod.ImageExists)).Methods(http.MethodGet)
583+
// swagger:operation GET /libpod/images/{name:.*}/tree libpod libpodImageTree
584584
// ---
585585
// tags:
586586
// - images
@@ -605,7 +605,7 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
605605
// $ref: '#/responses/NoSuchImage'
606606
// 500:
607607
// $ref: '#/responses/InternalError'
608-
r.Handle(VersionedPath("/libpod/images/{name:.*}/tree"), s.APIHandler(libpod.ImageTree))
608+
r.Handle(VersionedPath("/libpod/images/{name:.*}/tree"), s.APIHandler(libpod.ImageTree)).Methods(http.MethodGet)
609609
// swagger:operation GET /libpod/images/{name:.*}/history libpod libpodImageHistory
610610
// ---
611611
// tags:
@@ -852,7 +852,7 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
852852
// 500:
853853
// $ref: '#/responses/InternalError'
854854
r.Handle(VersionedPath("/libpod/images/{name:.*}"), s.APIHandler(handlers.RemoveImage)).Methods(http.MethodDelete)
855-
// swagger:operation GET /libpod/images/{name:.*}/get libpod libpoodExportImage
855+
// swagger:operation GET /libpod/images/{name:.*}/get libpod libpodExportImage
856856
// ---
857857
// tags:
858858
// - images
@@ -906,7 +906,7 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
906906
// $ref: '#/responses/NoSuchImage'
907907
// 500:
908908
// $ref: '#/responses/InternalError'
909-
r.Handle(VersionedPath("/libpod/images/{name:.*}/json"), s.APIHandler(libpod.GetImage))
909+
r.Handle(VersionedPath("/libpod/images/{name:.*}/json"), s.APIHandler(libpod.GetImage)).Methods(http.MethodGet)
910910
// swagger:operation POST /libpod/images/{name:.*}/tag libpod libpodTagImage
911911
// ---
912912
// tags:

‎pkg/api/server/register_system.go‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
11
package server
22

33
import (
4+
"net/http"
5+
46
"github.com/containers/libpod/pkg/api/handlers/generic"
57
"github.com/gorilla/mux"
68
)
79

810
func (s *APIServer) registerSystemHandlers(r *mux.Router) error {
9-
r.Handle(VersionedPath("/system/df"), s.APIHandler(generic.GetDiskUsage))
11+
r.Handle(VersionedPath("/system/df"), s.APIHandler(generic.GetDiskUsage)).Methods(http.MethodGet)
1012
return nil
1113
}

‎pkg/api/server/register_version.go‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,14 @@
11
package server
22

33
import (
4+
"net/http"
5+
46
"github.com/containers/libpod/pkg/api/handlers"
57
"github.com/gorilla/mux"
68
)
79

810
func (s *APIServer) registerVersionHandlers(r *mux.Router) error {
9-
r.Handle("/version", s.APIHandler(handlers.VersionHandler))
10-
r.Handle(VersionedPath("/version"), s.APIHandler(handlers.VersionHandler))
11+
r.Handle("/version", s.APIHandler(handlers.VersionHandler)).Methods(http.MethodGet)
12+
r.Handle(VersionedPath("/version"), s.APIHandler(handlers.VersionHandler)).Methods(http.MethodGet)
1113
return nil
1214
}

‎pkg/api/server/register_volumes.go‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ func (s *APIServer) registerVolumeHandlers(r *mux.Router) error {
2020
// "$ref": "#/responses/InternalError"
2121
r.Handle("/libpod/volumes/create", s.APIHandler(libpod.CreateVolume)).Methods(http.MethodPost)
2222
r.Handle("/libpod/volumes/json", s.APIHandler(libpod.ListVolumes)).Methods(http.MethodGet)
23-
// swagger:operation POST /volumes/prune volumes pruneVolumes
23+
// swagger:operation POST /libpod/volumes/prune volumes pruneVolumes
2424
// ---
2525
// summary: Prune volumes
2626
// produces:
@@ -31,7 +31,7 @@ func (s *APIServer) registerVolumeHandlers(r *mux.Router) error {
3131
// '500':
3232
// "$ref": "#/responses/InternalError"
3333
r.Handle("/libpod/volumes/prune", s.APIHandler(libpod.PruneVolumes)).Methods(http.MethodPost)
34-
// swagger:operation GET /volumes/{name}/json volumes inspectVolume
34+
// swagger:operation GET /libpod/volumes/{name}/json volumes inspectVolume
3535
// ---
3636
// summary: Inspect volume
3737
// parameters:
@@ -50,7 +50,7 @@ func (s *APIServer) registerVolumeHandlers(r *mux.Router) error {
5050
// '500':
5151
// "$ref": "#/responses/InternalError"
5252
r.Handle("/libpod/volumes/{name}/json", s.APIHandler(libpod.InspectVolume)).Methods(http.MethodGet)
53-
// swagger:operation DELETE /volumes/{name} volumes removeVolume
53+
// swagger:operation DELETE /libpod/volumes/{name} volumes removeVolume
5454
// ---
5555
// summary: Remove volume
5656
// parameters:

0 commit comments

Comments
 (0)