opensource/podman
1
0
Fork 0
mirror of https://github.com/containers/podman.git synced 2025-07-15 03:02:52 +08:00
Code Issues Packages Projects Releases Wiki Activity

Enable swagger validation for each PR

Browse Source 
* Update swagger:operation's to pass validation
* 'name' path parameter now used throughout API
* Added #/response/ok for 200 returns, TBD values have been replaced
  with legal values.

Signed-off-by: Jhon Honce <jhonce@redhat.com>
This commit is contained in:
Jhon Honce
2020-01-22 10:41:35 -07:00
parent c42383f70a
commit da1186ae63
14 changed files with 815 additions and 762 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
pkg/api/Makefile
View File

@ -2,12 +2,12 @@ export GO111MODULE=off
SWAGGER_OUT ?= swagger.yaml
validate: ${SWAGGER_OUT}
swagger validate ${SWAGGER_OUT}
.PHONY: ${SWAGGER_OUT}
${SWAGGER_OUT}:
# generate doesn't remove file on error
rm -f ${SWAGGER_OUT}
swagger generate spec -o ${SWAGGER_OUT} -w ./
swagger generate spec -o ${SWAGGER_OUT} -i tags.yaml -w ./
# TODO: when pass validation move it under swagger.
validate:
swagger validate ${SWAGGER_OUT}

4
pkg/api/handlers/swagger.go
View File

@ -96,9 +96,7 @@ type swagLibpodInspectContainerResponse struct {
// swagger:response ListPodsResponse
type swagListPodsResponse struct {
// in:body
Body struct {
libpod.PodInspect
}
Body []libpod.PodInspect
}
// Inspect pod

22
pkg/api/handlers/utils/errors.go
View File

@ -27,34 +27,34 @@ func Error(w http.ResponseWriter, apiMessage string, code int, err error) {
WriteJSON(w, code, em)
}
func VolumeNotFound(w http.ResponseWriter, nameOrId string, err error) {
func VolumeNotFound(w http.ResponseWriter, name string, err error) {
if errors.Cause(err) != define.ErrNoSuchVolume {
InternalServerError(w, err)
}
msg := fmt.Sprintf("No such volume: %s", nameOrId)
msg := fmt.Sprintf("No such volume: %s", name)
Error(w, msg, http.StatusNotFound, err)
}
func ContainerNotFound(w http.ResponseWriter, nameOrId string, err error) {
func ContainerNotFound(w http.ResponseWriter, name string, err error) {
if errors.Cause(err) != define.ErrNoSuchCtr {
InternalServerError(w, err)
}
msg := fmt.Sprintf("No such container: %s", nameOrId)
msg := fmt.Sprintf("No such container: %s", name)
Error(w, msg, http.StatusNotFound, err)
}
func ImageNotFound(w http.ResponseWriter, nameOrId string, err error) {
func ImageNotFound(w http.ResponseWriter, name string, err error) {
if errors.Cause(err) != define.ErrNoSuchImage {
InternalServerError(w, err)
}
msg := fmt.Sprintf("No such image: %s", nameOrId)
msg := fmt.Sprintf("No such image: %s", name)
Error(w, msg, http.StatusNotFound, err)
}
func PodNotFound(w http.ResponseWriter, nameOrId string, err error) {
func PodNotFound(w http.ResponseWriter, name string, err error) {
if errors.Cause(err) != define.ErrNoSuchPod {
InternalServerError(w, err)
}
msg := fmt.Sprintf("No such pod: %s", nameOrId)
msg := fmt.Sprintf("No such pod: %s", name)
Error(w, msg, http.StatusNotFound, err)
}
@ -73,9 +73,11 @@ func BadRequest(w http.ResponseWriter, key string, value string, err error) {
}
type ErrorModel struct {
// root cause
// API root cause formatted for automated parsing
// example: API root cause
Because string `json:"cause"`
// error message
// human error message, formatted for a human to read
// example: human error message
Message string `json:"message"`
}

29
pkg/api/server/docs.go Normal file
View File

@ -0,0 +1,29 @@
// Package api Provides a container compatible interface. (Experimental)
//
// This documentation describes the HTTP Libpod interface. It is to be considered
// only as experimental as this point. The endpoints, parameters, inputs, and
// return values can all change.
//
// Terms Of Service:
//
// Schemes: http, https
// Host: podman.io
// BasePath: /
// Version: 0.0.1
// License: Apache-2.0 https://opensource.org/licenses/Apache-2.0
// Contact: Podman <podman@lists.podman.io> https://podman.io/community/
// Extensions:
// x-logo:
// - url: https://raw.githubusercontent.com/containers/libpod/master/logo/podman-logo.png
// - altText: "Podman logo"
//
// Produces:
// - application/json
// - text/plain
// - text/html
//
// Consumes:
// - application/json
// - application/x-tar
// swagger:meta
package server

737
pkg/api/server/register_containers.go
View File

File diff suppressed because it is too large Load Diff

2
pkg/api/server/register_distribution.go
View File

@ -6,6 +6,6 @@ import (
)
func (s *APIServer) RegisterDistributionHandlers(r *mux.Router) error {
r.HandleFunc(VersionedPath("/distribution/{name:..*}/json"), handlers.UnsupportedHandler)
r.HandleFunc(VersionedPath("/distribution/{name}/json"), handlers.UnsupportedHandler)
return nil
}

13
pkg/api/server/register_events.go
View File

@ -8,24 +8,29 @@ import (
func (s *APIServer) RegisterEventsHandlers(r *mux.Router) error {
// swagger:operation GET /events system getEvents
// ---
// tags:
// - system
// summary: Returns events filtered on query parameters
// description: Returns events filtered on query parameters
// produces:
// - application/json
// parameters:
// - name: since
// type: string
// in: query
// description: start streaming events from this time
// - name: until
// type: string
// in: query
// description: stop streaming events later than this
// - name: filters
// type: string
// in: query
// description: JSON encoded map[string][]string of constraints
// responses:
// "200":
// description: OK
// "500":
// description: Failed
// 200:
// $ref: "#/responses/ok"
// 500:
// "$ref": "#/responses/InternalError"
r.Handle(VersionedPath("/events"), APIHandler(s.Context, handlers.GetEvents))
return nil

2
pkg/api/server/register_healthcheck.go
View File

@ -8,6 +8,6 @@ import (
)
func (s *APIServer) registerHealthCheckHandlers(r *mux.Router) error {
r.Handle(VersionedPath("/libpod/containers/{name:..*}/runhealthcheck"), APIHandler(s.Context, libpod.RunHealthCheck)).Methods(http.MethodGet)
r.Handle(VersionedPath("/libpod/containers/{name}/runhealthcheck"), APIHandler(s.Context, libpod.RunHealthCheck)).Methods(http.MethodGet)
return nil
}

297
pkg/api/server/register_images.go
View File

@ -11,11 +11,10 @@ import (
func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
// swagger:operation POST /images/create compat createImage
//
// ---
// tags:
// - images (compat)
// summary: Create an image from an image
// summary: Create an image
// description: Create an image by either pulling it from a registry or importing it.
// produces:
// - application/json
@ -25,53 +24,30 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
// type: string
// description: needs description
// - in: query
// name: tag
// type: string
// description: needs description
// responses:
// '200':
// schema:
// items:
// $ref: "to be determined"
// '404':
// description: repo or image does not exist
// schema:
// $ref: "#/responses/InternalError"
// '500':
// description: unexpected error
// schema:
// $ref: '#/responses/GenericError'
r.Handle(VersionedPath("/images/create"), APIHandler(s.Context, generic.CreateImageFromImage)).Methods(http.MethodPost).Queries("fromImage", "{fromImage}")
// swagger:operation POST /images/create compat createImage
// ---
// tags:
// - images (compat)
// summary: Create an image from Source
// description: Create an image by either pulling it from a registry or importing it.
// produces:
// - application/json
// parameters:
// - in: query
// name: fromSrc
// type: string
// description: needs description
// - in: query
// name: changes
// type: to be determined
// name: tag
// type: string
// description: needs description
// - in: header
// name: X-Registry-Auth
// type: string
// description: A base64-encoded auth configuration.
// - in: body
// name: request
// schema:
// type: string
// description: Image content if fromSrc parameter was used
// responses:
// '200':
// schema:
// items:
// $ref: "to be determined"
// '404':
// description: repo or image does not exist
// schema:
// 200:
// $ref: "#/responses/ok"
// 404:
// $ref: "#/responses/NoSuchImage"
// 500:
// $ref: "#/responses/InternalError"
// '500':
// description: unexpected error
// schema:
// $ref: '#/responses/GenericError'
r.Handle(VersionedPath("/images/create"), APIHandler(s.Context, generic.CreateImageFromImage)).Methods(http.MethodPost).Queries("fromImage", "{fromImage}")
r.Handle(VersionedPath("/images/create"), APIHandler(s.Context, generic.CreateImageFromSrc)).Methods(http.MethodPost).Queries("fromSrc", "{fromSrc}")
// swagger:operation GET /images/json compat listImages
// ---
@ -82,17 +58,12 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
// produces:
// - application/json
// responses:
// '200':
// schema:
// type: array
// items:
// schema:
// 200:
// $ref: "#/responses/DockerImageSummary"
// '500':
// 500:
// $ref: '#/responses/InternalError'
r.Handle(VersionedPath("/images/json"), APIHandler(s.Context, generic.GetImages)).Methods(http.MethodGet)
// swagger:operation POST /images/load compat loadImage
//
// ---
// tags:
// - images (compat)
@ -101,18 +72,19 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
// parameters:
// - in: query
// name: quiet
// type: bool
// type: boolean
// description: not supported
// - in: body
// name: request
// description: tarball of container image
// schema:
// type: string
// format: binary
// produces:
// - application/json
// responses:
// '200':
// 200:
// description: no error
// '500':
// 500:
// $ref: '#/responses/InternalError'
r.Handle(VersionedPath("/images/load"), APIHandler(s.Context, handlers.LoadImage)).Methods(http.MethodPost)
// swagger:operation POST /images/prune compat pruneImages
@ -135,11 +107,9 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
// produces:
// - application/json
// responses:
// '200':
// schema:
// items:
// 200:
// $ref: "#/responses/DocsImageDeleteResponse"
// '500':
// 500:
// $ref: '#/responses/InternalError'
r.Handle(VersionedPath("/images/prune"), APIHandler(s.Context, generic.PruneImages)).Methods(http.MethodPost)
// swagger:operation GET /images/search compat searchImages
@ -155,7 +125,7 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
// description: term to search
// - in: query
// name: limit
// type: int
// type: integer
// description: maximum number of results
// - in: query
// name: filters
@ -168,39 +138,44 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
// produces:
// - application/json
// responses:
// '200':
// 200:
// $ref: "#/responses/DocsSearchResponse"
// '500':
// 500:
// $ref: '#/responses/InternalError'
r.Handle(VersionedPath("/images/search"), APIHandler(s.Context, handlers.SearchImages)).Methods(http.MethodGet)
// swagger:operation DELETE /images/{nameOrID} compat removeImage
// swagger:operation DELETE /images/{name} compat removeImage
// ---
// tags:
// - images (compat)
// summary: Remove Image
// description: Delete an image from local storage
// parameters:
// - in: path
// name: name
// type: string
// required: true
// description: name or ID of image to delete
// - in: query
// name: force
// type: bool
// type: boolean
// description: remove the image even if used by containers or has other tags
// - in: query
// name: noprune
// type: bool
// type: boolean
// description: not supported. will be logged as an invalid parameter if enabled
// produces:
// - application/json
// responses:
// '200':
// 200:
// $ref: "#/responses/DocsImageDeleteResponse"
// '404':
// 404:
// $ref: '#/responses/NoSuchImage'
// '409':
// 409:
// $ref: '#/responses/ConflictError'
// '500':
// 500:
// $ref: '#/responses/InternalError'
r.Handle(VersionedPath("/images/{name:..*}"), APIHandler(s.Context, handlers.RemoveImage)).Methods(http.MethodDelete)
// swagger:operation GET /images/{nameOrID}/get compat exportImage
r.Handle(VersionedPath("/images/name"), APIHandler(s.Context, handlers.RemoveImage)).Methods(http.MethodDelete)
// swagger:operation GET /images/{name}/get compat exportImage
// ---
// tags:
// - images (compat)
@ -208,21 +183,22 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
// description: Export an image in tarball format
// parameters:
// - in: path
// name: nameOrID
// name: name
// type: string
// required: true
// description: the name or ID of the container
// produces:
// - application/json
// responses:
// '200':
// 200:
// description: no error
// schema:
// type: string
// format: binary
// '500':
// 500:
// $ref: '#/responses/InternalError'
r.Handle(VersionedPath("/images/{name:..*}/get"), APIHandler(s.Context, generic.ExportImage)).Methods(http.MethodGet)
// swagger:operation GET /images/{nameOrID}/history compat imageHistory
r.Handle(VersionedPath("/images/{name}/get"), APIHandler(s.Context, generic.ExportImage)).Methods(http.MethodGet)
// swagger:operation GET /images/{name}/history compat imageHistory
// ---
// tags:
// - images (compat)
@ -230,20 +206,21 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
// description: Return parent layers of an image.
// parameters:
// - in: path
// name: nameOrID
// name: name
// type: string
// required: true
// description: the name or ID of the container
// produces:
// - application/json
// responses:
// '200':
// 200:
// $ref: "#/responses/DocsHistory"
// '404':
// 404:
// $ref: "#/responses/NoSuchImage"
// '500':
// 500:
// $ref: "#/responses/InternalError"
r.Handle(VersionedPath("/images/{name:..*}/history"), APIHandler(s.Context, handlers.HistoryImage)).Methods(http.MethodGet)
// swagger:operation GET /images/{nameOrID}/json compat inspectImage
r.Handle(VersionedPath("/images/{name}/history"), APIHandler(s.Context, handlers.HistoryImage)).Methods(http.MethodGet)
// swagger:operation GET /images/{name}/json compat inspectImage
// ---
// tags:
// - images (compat)
@ -251,20 +228,21 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
// description: Return low-level information about an image.
// parameters:
// - in: path
// name: nameOrID
// name: name
// type: string
// required: true
// description: the name or ID of the container
// produces:
// - application/json
// responses:
// '200':
// 200:
// $ref: "#/responses/DocsImageInspect"
// '404':
// 404:
// $ref: "#/responses/NoSuchImage"
// '500':
// 500:
// $ref: "#/responses/InternalError"
r.Handle(VersionedPath("/images/{name:..*}/json"), APIHandler(s.Context, generic.GetImage))
// swagger:operation POST /images/{nameOrID}/tag compat tagImage
r.Handle(VersionedPath("/images/{name}/json"), APIHandler(s.Context, generic.GetImage))
// swagger:operation POST /images/{name}/tag compat tagImage
// ---
// tags:
// - images (compat)
@ -272,7 +250,8 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
// description: Tag an image so that it becomes part of a repository.
// parameters:
// - in: path
// name: nameOrID
// name: name
// type: string
// required: true
// description: the name or ID of the container
// - in: query
@ -296,7 +275,7 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
// $ref: '#/responses/ConflictError'
// 500:
// $ref: '#/responses/InternalError'
r.Handle(VersionedPath("/images/{name:..*}/tag"), APIHandler(s.Context, handlers.TagImage)).Methods(http.MethodPost)
r.Handle(VersionedPath("/images/{name}/tag"), APIHandler(s.Context, handlers.TagImage)).Methods(http.MethodPost)
// swagger:operation POST /commit/ compat commitContainer
// ---
// tags:
@ -325,7 +304,7 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
// description: author of the image
// - in: query
// name: pause
// type: bool
// type: boolean
// description: pause the container before committing it
// - in: query
// name: changes
@ -334,11 +313,11 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
// produces:
// - application/json
// responses:
// '201':
// 201:
// description: no error
// '404':
// 404:
// $ref: '#/responses/NoSuchImage'
// '500':
// 500:
// $ref: '#/responses/InternalError'
r.Handle(VersionedPath("/commit"), APIHandler(s.Context, generic.CommitContainer)).Methods(http.MethodPost)
@ -542,15 +521,20 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
// properties:
// stream:
// type: string
// description: output from build process
// example: |
// (build details...)
// Successfully built 8ba084515c724cbf90d447a63600c0a6
// 400:
// $ref: "#/responses/BadParamError"
// 500:
// $ref: "#/responses/InternalError"
r.Handle(VersionedPath("/build"), APIHandler(s.Context, handlers.BuildImage)).Methods(http.MethodPost)
/*
libpod endpoints
*/
// swagger:operation POST /libpod/images/{nameOrID}/exists libpod libpodImageExists
// swagger:operation POST /libpod/images/{name}/exists libpod libpodImageExists
// ---
// tags:
// - images
@ -558,21 +542,22 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
// description: Check if image exists in local store
// parameters:
// - in: path
// name: nameOrID
// name: name
// type: string
// required: true
// description: the name or ID of the container
// produces:
// - application/json
// responses:
// '204':
// 204:
// description: image exists
// '404':
// 404:
// $ref: '#/responses/NoSuchImage'
// '500':
// 500:
// $ref: '#/responses/InternalError'
r.Handle(VersionedPath("/libpod/images/{name:..*}/exists"), APIHandler(s.Context, libpod.ImageExists))
r.Handle(VersionedPath("/libpod/images/{name:..*}/tree"), APIHandler(s.Context, libpod.ImageTree))
// swagger:operation GET /libpod/images/{nameOrID}/history libpod libpodImageHistory
r.Handle(VersionedPath("/libpod/images/{name}/exists"), APIHandler(s.Context, libpod.ImageExists))
r.Handle(VersionedPath("/libpod/images/{name}/tree"), APIHandler(s.Context, libpod.ImageTree))
// swagger:operation GET /libpod/images/{name}/history libpod libpodImageHistory
// ---
// tags:
// - images
@ -580,21 +565,20 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
// description: Return parent layers of an image.
// parameters:
// - in: path
// name: nameOrID
// name: name
// type: string
// required: true
// description: the name or ID of the container
// produces:
// - application/json
// responses:
// '200':
// schema:
// items:
// $ref: "#/responses/HistoryResponse"
// '404':
// 200:
// $ref: "#/responses/DocsHistory"
// 404:
// $ref: '#/responses/NoSuchImage'
// '500':
// 500:
// $ref: '#/responses/InternalError'
r.Handle(VersionedPath("/libpod/images/history"), APIHandler(s.Context, handlers.HistoryImage)).Methods(http.MethodGet)
r.Handle(VersionedPath("/libpod/images/{name}/history"), APIHandler(s.Context, handlers.HistoryImage)).Methods(http.MethodGet)
// swagger:operation GET /libpod/images/json libpod libpodListImages
// ---
// tags:
@ -604,9 +588,9 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
// produces:
// - application/json
// responses:
// '200':
// 200:
// $ref: "#/responses/DockerImageSummary"
// '500':
// 500:
// $ref: '#/responses/InternalError'
r.Handle(VersionedPath("/libpod/images/json"), APIHandler(s.Context, libpod.GetImages)).Methods(http.MethodGet)
// swagger:operation POST /libpod/images/load libpod libpodLoadImage
@ -618,18 +602,20 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
// parameters:
// - in: query
// name: quiet
// type: bool
// type: boolean
// description: not supported
// - in: body
// name: request
// description: tarball of container image
// required: true
// schema:
// type: string
// format: binary
// produces:
// - application/json
// responses:
// '200':
// 200:
// description: no error
// '500':
// 500:
// $ref: '#/responses/InternalError'
r.Handle(VersionedPath("/libpod/images/load"), APIHandler(s.Context, handlers.LoadImage)).Methods(http.MethodPost)
// swagger:operation POST /libpod/images/prune libpod libpodPruneImages
@ -651,15 +637,14 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
// - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels.
// - in: query
// name: all
// type: bool
// type: boolean
// description: prune all images
// produces:
// - application/json
// responses:
// '200':
// items:
// 200:
// $ref: "#/responses/DocsImageDeleteResponse"
// '500':
// 500:
// $ref: '#/responses/InternalError'
r.Handle(VersionedPath("/libpod/images/prune"), APIHandler(s.Context, libpod.PruneImages)).Methods(http.MethodPost)
// swagger:operation GET /libpod/images/search libpod libpodSearchImages
@ -675,7 +660,7 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
// description: term to search
// - in: query
// name: limit
// type: int
// type: integer
// description: maximum number of results
// - in: query
// name: filters
@ -688,37 +673,42 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
// produces:
// - application/json
// responses:
// '200':
// schema:
// items:
// 200:
// $ref: "#/responses/DocsSearchResponse"
// '500':
// 500:
// $ref: '#/responses/InternalError'
r.Handle(VersionedPath("/libpod/images/search"), APIHandler(s.Context, handlers.SearchImages)).Methods(http.MethodGet)
// swagger:operation DELETE /libpod/images/{nameOrID} libpod libpodRemoveImage
// swagger:operation DELETE /libpod/images/{name} libpod libpodRemoveImage
// ---
// tags:
// - images
// summary: Remove Image
// description: Delete an image from local store
// parameters:
// - in: path
// name: name
// type: string
// required: true
// description: name or ID of image to delete
// - in: query
// name: force
// type: bool
// type: boolean
// description: remove the image even if used by containers or has other tags
// produces:
// - application/json
// responses:
// '200':
// 200:
// $ref: "#/responses/DocsImageDeleteResponse"
// '404':
// 400:
// $ref: "#/responses/BadParamError"
// 404:
// $ref: '#/responses/NoSuchImage'
// '409':
// 409:
// $ref: '#/responses/ConflictError'
// '500':
// 500:
// $ref: '#/responses/InternalError'
r.Handle(VersionedPath("/libpod/images/{name:..*}"), APIHandler(s.Context, handlers.RemoveImage)).Methods(http.MethodDelete)
// swagger:operation GET /libpod/images/{nameOrID}/get libpod libpoodExportImage
r.Handle(VersionedPath("/libpod/images/name"), APIHandler(s.Context, handlers.RemoveImage)).Methods(http.MethodDelete)
// swagger:operation GET /libpod/images/{name}/get libpod libpoodExportImage
// ---
// tags:
// - images
@ -726,33 +716,32 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
// description: Export an image as a tarball
// parameters:
// - in: path
// name: nameOrID
// name: name
// type: string
// required: true
// description: the name or ID of the container
// - in: query
// name: format
// type: string
// description: format for exported image
// default: oci-archive
// - in: query
// name: compress
// type: bool
// type: boolean
// description: use compression on image
// default: false
// produces:
// - application/json
// responses:
// '200':
// 200:
// description: no error
// schema:
// type: string
// format: binary
// '404':
// 404:
// $ref: '#/responses/NoSuchImage'
// '500':
// 500:
// $ref: '#/responses/InternalError'
r.Handle(VersionedPath("/libpod/images/{name:..*}/get"), APIHandler(s.Context, libpod.ExportImage)).Methods(http.MethodGet)
// swagger:operation GET /libpod/images/{nameOrID}/json libpod libpodInspectImage
r.Handle(VersionedPath("/libpod/images/{name}/get"), APIHandler(s.Context, libpod.ExportImage)).Methods(http.MethodGet)
// swagger:operation GET /libpod/images/{name}/json libpod libpodInspectImage
// ---
// tags:
// - images
@ -760,20 +749,21 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
// description: Obtain low-level information about an image
// parameters:
// - in: path
// name: nameOrID
// name: name
// type: string
// required: true
// description: the name or ID of the container
// produces:
// - application/json
// responses:
// '200':
// 200:
// $ref: "#/responses/DocsLibpodInspectImageResponse"
// '404':
// 404:
// $ref: '#/responses/NoSuchImage'
// '500':
// 500:
// $ref: '#/responses/InternalError'
r.Handle(VersionedPath("/libpod/images/{name:..*}/json"), APIHandler(s.Context, libpod.GetImage))
// swagger:operation POST /libpod/images/{nameOrID}/tag libpod libpodTagImage
r.Handle(VersionedPath("/libpod/images/{name}/json"), APIHandler(s.Context, libpod.GetImage))
// swagger:operation POST /libpod/images/{name}/tag libpod libpodTagImage
// ---
// tags:
// - images
@ -781,7 +771,8 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
// description: Tag an image so that it becomes part of a repository.
// parameters:
// - in: path
// name: nameOrID
// name: name
// type: string
// required: true
// description: the name or ID of the container
// - in: query
@ -795,17 +786,17 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
// produces:
// - application/json
// responses:
// '201':
// 201:
// description: no error
// '400':
// 400:
// $ref: '#/responses/BadParamError'
// '404':
// 404:
// $ref: '#/responses/NoSuchImage'
// '409':
// 409:
// $ref: '#/responses/ConflictError'
// '500':
// 500:
// $ref: '#/responses/InternalError'
r.Handle(VersionedPath("/libpod/images/{name:..*}/tag"), APIHandler(s.Context, handlers.TagImage)).Methods(http.MethodPost)
r.Handle(VersionedPath("/libpod/images/{name}/tag"), APIHandler(s.Context, handlers.TagImage)).Methods(http.MethodPost)
return nil
}

8
pkg/api/server/register_info.go
View File

@ -10,15 +10,17 @@ import (
func (s *APIServer) registerInfoHandlers(r *mux.Router) error {
// swagger:operation GET /info libpod libpodGetInfo
// ---
// tags:
// - system
// summary: Get info
// description: Returns information on the system and libpod configuration
// produces:
// - application/json
// responses:
// '200':
// 200:
// description: to be determined
// '500':
// "$ref": "#/responses/InternalError"
// 500:
// $ref: "#/responses/InternalError"
r.Handle(VersionedPath("/info"), APIHandler(s.Context, generic.GetInfo)).Methods(http.MethodGet)
return nil
}

154
pkg/api/server/register_pods.go
View File

@ -16,16 +16,14 @@ func (s *APIServer) registerPodsHandlers(r *mux.Router) error {
// parameters:
// - in: query
// name: filters
// descriptions: needs description and plumbing for filters
// type: string
// description: needs description and plumbing for filters
// responses:
// '200':
// properties:
// items:
// 200:
// $ref: "#/responses/ListPodsResponse"
// type: array
// '400':
// 400:
// $ref: "#/responses/BadParamError"
// '500':
// 500:
// $ref: "#/responses/InternalError"
r.Handle(VersionedPath("/libpod/pods/json"), APIHandler(s.Context, libpod.Pods)).Methods(http.MethodGet)
r.Handle(VersionedPath("/libpod/pods/create"), APIHandler(s.Context, libpod.PodCreate)).Methods(http.MethodPost)
@ -36,61 +34,63 @@ func (s *APIServer) registerPodsHandlers(r *mux.Router) error {
// - in: query
// name: force
// description: force delete
// type: bool
// type: boolean
// default: false
// produces:
// - application/json
// responses:
// '204':
// 204:
// description: no error
// '400':
// 400:
// $ref: "#/responses/BadParamError"
// '500':
// 500:
// $ref: "#/responses/InternalError"
r.Handle(VersionedPath("/libpod/pods/prune"), APIHandler(s.Context, libpod.PodPrune)).Methods(http.MethodPost)
// swagger:operation DELETE /libpod/pods/{nameOrID} pods removePod
// swagger:operation DELETE /libpod/pods/{name} pods removePod
// ---
// summary: Remove pod
// produces:
// - application/json
// parameters:
// - in: path
// name: nameOrID
// name: name
// type: string
// required: true
// description: the name or ID of the pod
// - in: query
// name: force
// type: bool
// type: boolean
// description: force delete
// responses:
// '204':
// 204:
// description: no error
// '400':
// 400:
// $ref: "#/responses/BadParamError"
// '404':
// 404:
// $ref: "#/responses/NoSuchPod"
// '500':
// 500:
// $ref: "#/responses/InternalError"
r.Handle(VersionedPath("/libpod/pods/{name:..*}"), APIHandler(s.Context, libpod.PodDelete)).Methods(http.MethodDelete)
// swagger:operation GET /libpod/pods/{nameOrID}/json pods inspectPod
r.Handle(VersionedPath("/libpod/pods/{name}"), APIHandler(s.Context, libpod.PodDelete)).Methods(http.MethodDelete)
// swagger:operation GET /libpod/pods/{name}/json pods inspectPod
// ---
// summary: Inspect pod
// produces:
// - application/json
// parameters:
// - in: path
// name: nameOrID
// name: name
// type: string
// required: true
// description: the name or ID of the pod
// responses:
// '200':
// 200:
// $ref: "#/responses/InspectPodResponse"
// '404':
// 404:
// $ref: "#/responses/NoSuchPod"
// '500':
// 500:
// $ref: "#/responses/InternalError"
r.Handle(VersionedPath("/libpod/pods/{name:..*}/json"), APIHandler(s.Context, libpod.PodInspect)).Methods(http.MethodGet)
// swagger:operation GET /libpod/pods/{nameOrID}/exists pods podExists
r.Handle(VersionedPath("/libpod/pods/{name}/json"), APIHandler(s.Context, libpod.PodInspect)).Methods(http.MethodGet)
// swagger:operation GET /libpod/pods/{name}/exists pods podExists
// ---
// summary: Pod exists
// description: Check if a pod exists by name or ID
@ -98,25 +98,27 @@ func (s *APIServer) registerPodsHandlers(r *mux.Router) error {
// - application/json
// parameters:
// - in: path
// name: nameOrID
// name: name
// type: string
// required: true
// description: the name or ID of the pod
// responses:
// '204':
// 204:
// description: pod exists
// '404':
// 404:
// $ref: "#/responses/NoSuchPod"
// '500':
// 500:
// $ref: "#/responses/InternalError"
r.Handle(VersionedPath("/libpod/pods/{name:..*}/exists"), APIHandler(s.Context, libpod.PodExists)).Methods(http.MethodGet)
// swagger:operation POST /libpod/pods/{nameOrID}/kill pods killPod
r.Handle(VersionedPath("/libpod/pods/{name}/exists"), APIHandler(s.Context, libpod.PodExists)).Methods(http.MethodGet)
// swagger:operation POST /libpod/pods/{name}/kill pods killPod
// ---
// summary: Kill a pod
// produces:
// - application/json
// parameters:
// - in: path
// name: nameOrID
// name: name
// type: string
// required: true
// description: the name or ID of the pod
// - in: query
@ -125,116 +127,122 @@ func (s *APIServer) registerPodsHandlers(r *mux.Router) error {
// description: signal to be sent to pod
// default: SIGKILL
// responses:
// '204':
// 204:
// description: no error
// '400':
// 400:
// $ref: "#/responses/BadParamError"
// '404':
// 404:
// $ref: "#/responses/NoSuchPod"
// '409':
// 409:
// $ref: "#/responses/ConflictError"
// '500':
// 500:
// $ref: "#/responses/InternalError"
r.Handle(VersionedPath("/libpod/pods/{name:..*}/kill"), APIHandler(s.Context, libpod.PodKill)).Methods(http.MethodPost)
// swagger:operation POST /libpod/pods/{nameOrID}/pause pods pausePod
r.Handle(VersionedPath("/libpod/pods/{name}/kill"), APIHandler(s.Context, libpod.PodKill)).Methods(http.MethodPost)
// swagger:operation POST /libpod/pods/{name}/pause pods pausePod
// ---
// summary: Pause a pod
// description: Pause a pod
// produces:
// - application/json
// parameters:
// - in: path
// name: nameOrID
// name: name
// type: string
// required: true
// description: the name or ID of the pod
// responses:
// '204':
// 204:
// description: no error
// '404':
// 404:
// $ref: "#/responses/NoSuchPod"
// '500':
// 500:
// $ref: "#/responses/InternalError"
r.Handle(VersionedPath("/libpod/pods/{name:..*}/pause"), APIHandler(s.Context, libpod.PodPause)).Methods(http.MethodPost)
// swagger:operation POST /libpod/pods/{nameOrID}/restart pods restartPod
r.Handle(VersionedPath("/libpod/pods/{name}/pause"), APIHandler(s.Context, libpod.PodPause)).Methods(http.MethodPost)
// swagger:operation POST /libpod/pods/{name}/restart pods restartPod
// ---
// summary: Restart a pod
// produces:
// - application/json
// parameters:
// - in: path
// name: nameOrID
// name: name
// type: string
// required: true
// description: the name or ID of the pod
// responses:
// '204':
// 204:
// description: no error
// '404':
// 404:
// $ref: "#/responses/NoSuchPod"
// '500':
// 500:
// $ref: "#/responses/InternalError"
r.Handle(VersionedPath("/libpod/pods/{name:..*}/restart"), APIHandler(s.Context, libpod.PodRestart)).Methods(http.MethodPost)
// swagger:operation POST /libpod/pods/{nameOrID}/start pods startPod
r.Handle(VersionedPath("/libpod/pods/{name}/restart"), APIHandler(s.Context, libpod.PodRestart)).Methods(http.MethodPost)
// swagger:operation POST /libpod/pods/{name}/start pods startPod
// ---
// summary: Start a pod
// produces:
// - application/json
// parameters:
// - in: path
// name: nameOrID
// name: name
// type: string
// required: true
// description: the name or ID of the pod
// responses:
// '204':
// 204:
// description: no error
// '304':
// 304:
// $ref: "#/responses/PodAlreadyStartedError"
// '404':
// 404:
// $ref: "#/responses/NoSuchPod"
// '500':
// 500:
// $ref: "#/responses/InternalError"
r.Handle(VersionedPath("/libpod/pods/{name:..*}/start"), APIHandler(s.Context, libpod.PodStart)).Methods(http.MethodPost)
// swagger:operation POST /libpod/pods/{nameOrID}/stop pods stopPod
r.Handle(VersionedPath("/libpod/pods/{name}/start"), APIHandler(s.Context, libpod.PodStart)).Methods(http.MethodPost)
// swagger:operation POST /libpod/pods/{name}/stop pods stopPod
// ---
// summary: Stop a pod
// produces:
// - application/json
// parameters:
// - in: path
// name: nameOrID
// name: name
// type: string
// required: true
// description: the name or ID of the pod
// - in: query
// name: t
// type: int
// type: integer
// description: timeout
// responses:
// '204':
// 204:
// description: no error
// '304':
// 304:
// $ref: "#/responses/PodAlreadyStoppedError"
// '400':
// 400:
// $ref: "#/responses/BadParamError"
// '404':
// 404:
// $ref: "#/responses/NoSuchPod"
// '500':
// 500:
// $ref: "#/responses/InternalError"
r.Handle(VersionedPath("/libpod/pods/{name:..*}/stop"), APIHandler(s.Context, libpod.PodStop)).Methods(http.MethodPost)
// swagger:operation POST /libpod/pods/{nameOrID}/unpause pods unpausePod
r.Handle(VersionedPath("/libpod/pods/{name}/stop"), APIHandler(s.Context, libpod.PodStop)).Methods(http.MethodPost)
// swagger:operation POST /libpod/pods/{name}/unpause pods unpausePod
// ---
// summary: Unpause a pod
// produces:
// - application/json
// parameters:
// - in: path
// name: nameOrID
// name: name
// type: string
// required: true
// description: the name or ID of the pod
// responses:
// '204':
// 204:
// description: no error
// '404':
// 404:
// $ref: "#/responses/NoSuchPod"
// '500':
// 500:
// $ref: "#/responses/InternalError"
r.Handle(VersionedPath("/libpod/pods/{name:..*}/unpause"), APIHandler(s.Context, libpod.PodUnpause)).Methods(http.MethodPost)
r.Handle(VersionedPath("/libpod/pods/{name}/unpause"), APIHandler(s.Context, libpod.PodUnpause)).Methods(http.MethodPost)
return nil
}

30
pkg/api/server/register_volumes.go
View File

@ -31,12 +31,13 @@ func (s *APIServer) registerVolumeHandlers(r *mux.Router) error {
// '500':
// "$ref": "#/responses/InternalError"
r.Handle("/libpod/volumes/prune", APIHandler(s.Context, libpod.PruneVolumes)).Methods(http.MethodPost)
// swagger:operation GET /volumes/{nameOrID}/json volumes inspectVolume
// swagger:operation GET /volumes/{name}/json volumes inspectVolume
// ---
// summary: Inspect volume
// parameters:
// - in: path
// name: nameOrID
// name: name
// type: string
// required: true
// description: the name or ID of the volume
// produces:
@ -48,30 +49,31 @@ func (s *APIServer) registerVolumeHandlers(r *mux.Router) error {
// "$ref": "#/responses/NoSuchVolume"
// '500':
// "$ref": "#/responses/InternalError"
r.Handle("/libpod/volumes/{name:..*}/json", APIHandler(s.Context, libpod.InspectVolume)).Methods(http.MethodGet)
// swagger:operation DELETE /volumes/{nameOrID} volumes removeVolume
r.Handle("/libpod/volumes/{name}/json", APIHandler(s.Context, libpod.InspectVolume)).Methods(http.MethodGet)
// swagger:operation DELETE /volumes/{name} volumes removeVolume
// ---
// summary: Remove volume
// parameters:
// - in: path
// name: nameOrID
// name: name
// type: string
// required: true
// description: the name or ID of the volume
// - in: query
// name: force
// type: bool
// type: boolean
// description: force removal
// produces:
// - application/json
// responses:
// '204':
// 204:
// description: no error
// '400':
// "$ref": "#/responses/BadParamError"
// '404':
// "$ref": "#/responses/NoSuchVolume"
// '500':
// "$ref": "#/responses/InternalError"
r.Handle("/libpod/volumes/{name:..*}", APIHandler(s.Context, libpod.RemoveVolume)).Methods(http.MethodDelete)
// 400:
// $ref: "#/responses/BadParamError"
// 404:
// $ref: "#/responses/NoSuchVolume"
// 500:
// $ref: "#/responses/InternalError"
r.Handle("/libpod/volumes/{name}", APIHandler(s.Context, libpod.RemoveVolume)).Methods(http.MethodDelete)
return nil
}

41
pkg/api/server/server.go
View File

@ -1,44 +1,3 @@
// Package api Provides a container compatible interface.
//
// This documentation describes the HTTP Libpod interface. It is to be consider
// only as experimental as this point. The endpoints, parameters, inputs, and
// return values can all change.
//
// Schemes: http, https
// Host: podman.io
// BasePath: /
// Version: 0.0.1
// License: Apache-2.0 https://opensource.org/licenses/Apache-2.0
// Contact: Podman <podman@lists.podman.io> https://podman.io/community/
// InfoExtensions:
// x-logo:
// - url: https://raw.githubusercontent.com/containers/libpod/master/logo/podman-logo.png
// - altText: "Podman logo"
//
// Consumes:
// - application/json
// - application/x-tar
//
// Produces:
// - application/json
// - text/plain
// - text/html
//
// tags:
// - name: containers
// description: Actions related to containers
// - name: images
// description: Actions related to images
// - name: pods
// description: Actions related to pods
// - name: volumes
// description: Actions related to volumes
// - name: containers (compat)
// description: Actions related to containers for the compatibility endpoints
// - name: images (compat)
// description: Actions related to images for the compatibility endpoints
//
// swagger:meta
package server
import (

26
pkg/api/server/swagger.go
View File

@ -41,7 +41,7 @@ type swagErrNoSuchPod struct {
}
}
// Internal error
// Internal server error
// swagger:response InternalError
type swagInternalError struct {
// in:body
@ -59,7 +59,7 @@ type swagGenericError struct {
}
}
// Conflict error
// Conflict error in operation
// swagger:response ConflictError
type swagConflictError struct {
// in:body
@ -68,7 +68,7 @@ type swagConflictError struct {
}
}
// Bad parameter
// Bad parameter in request
// swagger:response BadParamError
type swagBadParamError struct {
// in:body
@ -134,3 +134,23 @@ type swagListContainers struct {
// swagger:response tbd
type swagTBD struct {
}
// Success
// swagger:response
type swag struct {
// in:body
Body struct {
// example: OK
ok string
}
}
// Success
// swagger:response
type ok struct {
// in:body
Body struct {
// example: OK
ok string
}
}