From 5b79cf15a0226dc3dad5053615ee652823376cd3 Mon Sep 17 00:00:00 2001 From: Jhon Honce Date: Thu, 19 May 2022 10:27:31 -0700 Subject: Swagger refactor/cleanup * Remove duplicate or unused types and constants * Move all documetation-only models and responses into swagger package * Remove all unecessary names, go-swagger will determine names from struct declarations * Use Libpod suffix to differentiate between compat and libpod models and responses. Taken from swagger:operation declarations. * Models and responses that start with lowercase are for swagger use only while uppercase are used "as is" in the code and swagger comments * Used gofumpt on new code ```release-note ``` Signed-off-by: Jhon Honce --- pkg/api/server/doc.go | 66 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 pkg/api/server/doc.go (limited to 'pkg/api/server/doc.go') diff --git a/pkg/api/server/doc.go b/pkg/api/server/doc.go new file mode 100644 index 000000000..0bb10a19c --- /dev/null +++ b/pkg/api/server/doc.go @@ -0,0 +1,66 @@ +// Package server supports a RESTful API for the Libpod library +// +// This documentation describes the Podman v2.x+ RESTful API. It consists of a Docker-compatible +// API and a Libpod API providing support for Podman’s unique features such as pods. +// +// To start the service and keep it running for 5,000 seconds (-t 0 runs forever): +// +// podman system service -t 5000 & +// +// You can then use cURL on the socket using requests documented below. +// +// NOTE: if you install the package podman-docker, it will create a symbolic +// link for /run/docker.sock to /run/podman/podman.sock +// +// NOTE: Some fields in the API response JSON are encoded as omitempty, which means that +// if said field has a zero value, they will not be encoded in the API response. This +// is a feature to help reduce the size of the JSON responses returned via the API. +// +// NOTE: Due to the limitations of [go-swagger](https://github.com/go-swagger/go-swagger), +// some field values that have a complex type show up as null in the docs as well as in the +// API responses. This is because the zero value for the field type is null. The field +// description in the docs will state what type the field is expected to be for such cases. +// +// See podman-service(1) for more information. +// +// Quick Examples: +// +// 'podman info' +// +// curl --unix-socket /run/podman/podman.sock http://d/v4.0.0/libpod/info +// +// 'podman pull quay.io/containers/podman' +// +// curl -XPOST --unix-socket /run/podman/podman.sock -v 'http://d/v4.0.0/images/create?fromImage=quay.io%2Fcontainers%2Fpodman' +// +// 'podman list images' +// +// curl --unix-socket /run/podman/podman.sock -v 'http://d/v4.0.0/libpod/images/json' | jq +// +// Terms Of Service: +// +// https://github.com/containers/podman/blob/913caaa9b1de2b63692c9bae15120208194c9eb3/LICENSE +// +// Schemes: http, https +// Host: podman.io +// BasePath: / +// Version: 4.0.0 +// License: Apache-2.0 https://opensource.org/licenses/Apache-2.0 +// Contact: Podman https://podman.io/community/ +// +// InfoExtensions: +// x-logo: +// - url: https://raw.githubusercontent.com/containers/libpod/main/logo/podman-logo.png +// - altText: "Podman logo" +// +// Produces: +// - application/json +// - application/octet-stream +// - text/plain +// +// Consumes: +// - application/json +// - application/x-tar +// +// swagger:meta +package server -- cgit v1.2.3-54-g00ecf