Docker Engine API v1.57.0 moves to OpenAPI 3.2: what to do

Docker Engine API is the interface that tools and applications use to interact with Docker Engine. The Docker Engine API v1.57.0 release updates the specification, changes how container events are represented, and fixes a schema related to image data.

Overview and technical details

Affected systems

The change is relevant to tools that rely on per-version Swagger 2.0 files. This release still provides a general Swagger 2.0 file and a version-pinned file for API v1.57, but future API versions will not have separate per-version Swagger 2.0 files. Tools depending on those files should therefore be migrated to OpenAPI 3.2 before upgrading to future API versions.

Mechanism and impact

For a container die event from GET /events, the restarting="true" property appears when the container is about to restart under a restart policy or following a manual restart operation. The property is omitted if the container does not restart, including while the daemon is stopped. It signals an intention to restart but does not guarantee that the restart will succeed or will not be canceled.

The release also fixes the ImageManifestSummary.ImageData schema: UnpackedSize does not exist; the unpacked size is reported in Size.Unpacked.

System checks

1. Check the API versions supported by the Docker Engine Client and Server, and compare the API version entries with API v1.57.

   Copy commands

   docker version

   This command does not confirm which API is available in a specific release.

Remediation and mitigation

1. Review internal tools that depend on per-version Swagger 2.0 files and plan to migrate to the OpenAPI 3.2 specification at api/openapi.yaml before upgrading to future API versions.

2. If Swagger 2.0 is needed, the general file remains available at api/swagger.yaml; the version-pinned file compatible with API v1.57 is at api/docs/v1.57-swagger.yaml.