swagger: possible inconsistencies #5238
Description
These are the inconsistencies my script sees in the // swagger:operation comments. I've organized them by what seems to me like a common grouping, and hope that it makes sense. Not all of these may be real issues, they're just confusing.
All files are under pkg/api/server. In some places I have adjusted whitespace for legibility.
Missing libpod prefix
The following names in register_containers.go are all missing the usual libpod prefix:
// swagger:operation GET /libpod/containers/showmounted libpod showMountedContainers
// swagger:operation POST /libpod/containers/{name}/mount libpod mountContainer
// swagger:operation GET /libpod/containers/{name}/exists libpod containerExists
(i.e. they should maybe be libpodShowMountedContainers, libpodMountContainer, libpodContainerExists for consistency with the 17 other paths defined here)
Incomplete names
The following names in register_containers.go should maybe include a Container suffix?
// swagger:operation POST /libpod/containers/{name}/attach libpod libpodAttach
// swagger:operation POST /libpod/containers/{name}/resize libpod libpodResize
The 18 other paths all include container or Container.
Inconsistent names (do not match the actual code).
For some reason I can't understand, register_images.go has a remarkable number of inconsistencies between the name on the right-hand side of the swagger line (operation ID) and the actual function being used. These inconsistencies probably aren't harmful, but they certainly make it difficult for a human to understand the relationships:
// swagger:operation POST /images/create compat createImage
r.Handle(VersionedPath("/images/create"), ... generic.CreateImageFromImage
// swagger:operation GET /images/json compat listImages
r.Handle(VersionedPath("/images/json"), ... generic.GetImages
// swagger:operation POST /images/load compat importImage
r.Handle(VersionedPath("/images/load"), ... generic.LoadImages
// swagger:operation GET /images/{name}/history compat imageHistory
r.Handle(VersionedPath("/images/{name}/history"), ... handlers.HistoryImage
// swagger:operation GET /images/{name}/json compat inspectImage
r.Handle(VersionedPath("/images/{name}/json"), ... generic.GetImage
// swagger:operation GET /libpod/images/{name}/history libpod libpodImageHistory
r.Handle(VersionedPath("/libpod/images/{name}/history"), ... handlers.HistoryImage
// swagger:operation GET /libpod/images/json libpod libpodListImages
r.Handle(VersionedPath("/libpod/images/json"), ... libpod.GetImages
// swagger:operation GET /libpod/images/{name}/json libpod libpodInspectImage
r.Handle(VersionedPath("/libpod/images/{name}/json"), ... libpod.GetImage
Unexpected tag and name
In register_info.go, I see:
// swagger:operation GET /info libpod libpodGetInfo
r.Handle(VersionedPath("/info"), ... generic.GetInfo
Shouldn't that be GET /info compat getInfo ?
Unexpected tags pods and volumes
Whereas everything else uses libpod as a tag, register_pods.go and register_volumes.go use pods and volumes respectively. Also, none of the names include a libpod prefix:
$ grep -h '// swagger:op' pkg/api/server/register_{pods,volumes}.go
(spacing edited for legibility)
// swagger:operation GET /libpod/pods/json pods ListPods *** Improper Capitalization
// swagger:operation POST /libpod/pods/prune pods PrunePods *** ditto
// swagger:operation DELETE /libpod/pods/{name} pods removePod
// swagger:operation GET /libpod/pods/{name}/json pods inspectPod
// swagger:operation GET /libpod/pods/{name}/exists pods podExists
// swagger:operation POST /libpod/pods/{name}/kill pods killPod
// swagger:operation POST /libpod/pods/{name}/pause pods pausePod
// swagger:operation POST /libpod/pods/{name}/restart pods restartPod
// swagger:operation POST /libpod/pods/{name}/start pods startPod
// swagger:operation POST /libpod/pods/{name}/stop pods stopPod
// swagger:operation POST /libpod/pods/{name}/unpause pods unpausePod
// swagger:operation POST /libpod/volumes/create volumes createVolume
// swagger:operation POST /libpod/volumes/prune volumes pruneVolumes
// swagger:operation GET /libpod/volumes/{name}/json volumes inspectVolume
// swagger:operation DELETE /libpod/volumes/{name} volumes removeVolume
This seems too consistent to be accidental, so I assume it's intentional, I just don't understand it.
Missing swagger comments
The following invocations are all missing // swagger:operation comments:
register_containers.go:
r.HandleFunc(VersionedPath("/libpod/containers/create"), ...
register_healthcheck.go:
r.Handle(VersionedPath("/libpod/containers/{name}/runhealthcheck"), ...
register_images.go:
r.Handle(VersionedPath("/images/create"), ...
register_ping.go:
r.Handle("/_ping", ... http.MethodGet
r.Handle("/_ping", ... http.MethodHead
r.Handle("/libpod/_ping", ... http.MethodHead
register_pods.go:
r.Handle(VersionedPath("/libpod/pods/create"), ...
register_system.go:
r.Handle(VersionedPath("/system/df"), ...
register_version.go:
r.Handle("/version", ....
r.Handle(VersionedPath("/version"), ...
register_volumes.go:
r.Handle("/libpod/volumes/json", ...