627a4cf7cc
full diff: a09e6e323e...a9507c6f76
Includes:
- moby/moby#40077 Update "auto-generate" comments to improve detection by linters
- moby/moby#40143 registry: add a critical section to protect authTransport.modReq
- moby/moby#40212 Move DefaultCapabilities() to caps package
- moby/moby#40021 Use newer x/sys/windows SecurityAttributes struct (carry 40017)
- carries moby/moby#40017 Use newer x/sys/windows SecurityAttributes struct
- moby/moby#40135 pkg/system: make OSVersion an alias for hcsshim OSVersion
- follow-up to moby/moby#39100 Use Microsoft/hcsshim constants and deprecate pkg/system.GetOsVersion()
- moby/moby#40250 Bump hcsshim to b3f49c06ffaeef24d09c6c08ec8ec8425a0303e2
- moby/moby#40243 Use certs.d from XDG_CONFIG_HOME when in rootless mode
- fixes moby/moby#40236 Docker rootless dies when unable to read /etc/docker/certs.d
- moby/moby#40283 Fix possible runtime panic in Lgetxattr
- moby/moby#40178 builder/remotecontext: small refactor
- moby/moby#40179 builder/remotecontext: allow ssh:// for remote context URLs
- fixes docker/cli#2164 Docker build cannot resolve git context with html escapes
- moby/moby#40302 client.ImagePush(): default to ":latest" instead of "all tags"
- relates to docker/cli#2214 [proposal] change "docker push" behavior to default to ":latest" instead of "all tags"
- relates to docker/cli#2220 implement docker push `-a`/ `--all-tags`
- moby/moby#40263 Normalize comment formatting
- moby/moby#40238 Allow client consumers like traefik to compile on illumos
- moby/moby#40108 bump google.golang.org/grpc v1.23.1
- moby/moby#40312 update vendor golang.org/x/sys to 6d18c012aee9febd81bbf9806760c8c4480e870d
- moby/moby#40247 pkg/system: deprecate constants in favor of golang.org/x/sys/windows
- moby/moby#40246 pkg/system: minor cleanups and remove use of deprecated system.GetOSVersion()
- moby/moby#40122 Update buildkit to containerd leases
- vendor: update buildkit to leases support (4f4e03067523b2fc5ca2f17514a5e75ad63e02fb)
- vendor: update containerd to acdcf13d5eaf0dfe0eaeabe7194a82535549bc2b
- vendor: update runc to d736ef14f0288d6993a1845745d6756cfc9ddd5a (v1.0.0-rc9)
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Working on the Engine API
The Engine API is an HTTP API used by the command-line client to communicate with the daemon. It can also be used by third-party software to control the daemon.
It consists of various components in this repository:
api/swagger.yamlA Swagger definition of the API.api/types/Types shared by both the client and server, representing various objects, options, responses, etc. Most are written manually, but some are automatically generated from the Swagger definition. See #27919 for progress on this.cli/The command-line client.client/The Go client used by the command-line client. It can also be used by third-party Go programs.daemon/The daemon, which serves the API.
Swagger definition
The API is defined by the Swagger definition in api/swagger.yaml. This definition can be used to:
- Automatically generate documentation.
- Automatically generate the Go server and client. (A work-in-progress.)
- Provide a machine readable version of the API for introspecting what it can do, automatically generating clients for other languages, etc.
Updating the API documentation
The API documentation is generated entirely from api/swagger.yaml. If you make updates to the API, edit this file to represent the change in the documentation.
The file is split into two main sections:
definitions, which defines re-usable objects used in requests and responsespaths, which defines the API endpoints (and some inline objects which don't need to be reusable)
To make an edit, first look for the endpoint you want to edit under paths, then make the required edits. Endpoints may reference reusable objects with $ref, which can be found in the definitions section.
There is hopefully enough example material in the file for you to copy a similar pattern from elsewhere in the file (e.g. adding new fields or endpoints), but for the full reference, see the Swagger specification.
swagger.yaml is validated by hack/validate/swagger to ensure it is a valid Swagger definition. This is useful when making edits to ensure you are doing the right thing.
Viewing the API documentation
When you make edits to swagger.yaml, you may want to check the generated API documentation to ensure it renders correctly.
Run make swagger-docs and a preview will be running at http://localhost. Some of the styling may be incorrect, but you'll be able to ensure that it is generating the correct documentation.
The production documentation is generated by vendoring swagger.yaml into docker/docker.github.io.