diff --git a/api/README.md b/api/README.md index 381f19881f..f2555794d2 100644 --- a/api/README.md +++ b/api/README.md @@ -1,4 +1,4 @@ -# Working on the Engine API +# 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. @@ -21,6 +21,7 @@ The API is defined by the [Swagger](http://swagger.io/specification/) definition ## 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. +Documentation for each API version can be found in the [docs directory](docs/README.md), which also provides a [CHANGELOG.md](docs/CHANGELOG.md). The file is split into two main sections: diff --git a/docs/api/version-history.md b/api/docs/CHANGELOG.md similarity index 100% rename from docs/api/version-history.md rename to api/docs/CHANGELOG.md diff --git a/api/docs/README.md b/api/docs/README.md new file mode 100644 index 0000000000..46bf79bdbe --- /dev/null +++ b/api/docs/README.md @@ -0,0 +1,26 @@ +# API Documentation + +This directory contains versioned documents for each version of the API +specification supported by this module. While this module provides support +for older API versions, support should be considered "best-effort", especially +for very old versions. Users are recommended to use the latest API versions, +and only rely on older API versions for compatibility with older clients. + +Newer API versions tend to be backward-compatible with older versions, +with some exceptions where features were deprecated. For an overview +of changes for each version, refer to [CHANGELOG.md](CHANGELOG.md). + +The latest version of the API specification can be found [at the root directory +of this module](../swagger.yaml) which may contain unreleased changes. + +For API version v1.24, documentation is only available in markdown +format, for later versions [Swagger (OpenAPI) v2.0](https://swagger.io/specification/v2/) +specifications can be found in this directory. The Moby project itself +primarily uses these swagger files to produce the API documentation; +while we attempt to make these files match the actual implementation, +the OpenAPI 2.0 specification has limitations that prevent us from +expressing all options provided. There may be discrepancies (for which +we welcome contributions). If you find bugs, or discrepancies, please +open a ticket (or pull request). + + diff --git a/docs/api/v1.24.md b/api/docs/v1.24.md similarity index 100% rename from docs/api/v1.24.md rename to api/docs/v1.24.md diff --git a/docs/api/v1.25.yaml b/api/docs/v1.25.yaml similarity index 100% rename from docs/api/v1.25.yaml rename to api/docs/v1.25.yaml diff --git a/docs/api/v1.26.yaml b/api/docs/v1.26.yaml similarity index 100% rename from docs/api/v1.26.yaml rename to api/docs/v1.26.yaml diff --git a/docs/api/v1.27.yaml b/api/docs/v1.27.yaml similarity index 100% rename from docs/api/v1.27.yaml rename to api/docs/v1.27.yaml diff --git a/docs/api/v1.28.yaml b/api/docs/v1.28.yaml similarity index 100% rename from docs/api/v1.28.yaml rename to api/docs/v1.28.yaml diff --git a/docs/api/v1.29.yaml b/api/docs/v1.29.yaml similarity index 100% rename from docs/api/v1.29.yaml rename to api/docs/v1.29.yaml diff --git a/docs/api/v1.30.yaml b/api/docs/v1.30.yaml similarity index 100% rename from docs/api/v1.30.yaml rename to api/docs/v1.30.yaml diff --git a/docs/api/v1.31.yaml b/api/docs/v1.31.yaml similarity index 100% rename from docs/api/v1.31.yaml rename to api/docs/v1.31.yaml diff --git a/docs/api/v1.32.yaml b/api/docs/v1.32.yaml similarity index 100% rename from docs/api/v1.32.yaml rename to api/docs/v1.32.yaml diff --git a/docs/api/v1.33.yaml b/api/docs/v1.33.yaml similarity index 100% rename from docs/api/v1.33.yaml rename to api/docs/v1.33.yaml diff --git a/docs/api/v1.34.yaml b/api/docs/v1.34.yaml similarity index 100% rename from docs/api/v1.34.yaml rename to api/docs/v1.34.yaml diff --git a/docs/api/v1.35.yaml b/api/docs/v1.35.yaml similarity index 100% rename from docs/api/v1.35.yaml rename to api/docs/v1.35.yaml diff --git a/docs/api/v1.36.yaml b/api/docs/v1.36.yaml similarity index 100% rename from docs/api/v1.36.yaml rename to api/docs/v1.36.yaml diff --git a/docs/api/v1.37.yaml b/api/docs/v1.37.yaml similarity index 100% rename from docs/api/v1.37.yaml rename to api/docs/v1.37.yaml diff --git a/docs/api/v1.38.yaml b/api/docs/v1.38.yaml similarity index 100% rename from docs/api/v1.38.yaml rename to api/docs/v1.38.yaml diff --git a/docs/api/v1.39.yaml b/api/docs/v1.39.yaml similarity index 100% rename from docs/api/v1.39.yaml rename to api/docs/v1.39.yaml diff --git a/docs/api/v1.40.yaml b/api/docs/v1.40.yaml similarity index 100% rename from docs/api/v1.40.yaml rename to api/docs/v1.40.yaml diff --git a/docs/api/v1.41.yaml b/api/docs/v1.41.yaml similarity index 100% rename from docs/api/v1.41.yaml rename to api/docs/v1.41.yaml diff --git a/docs/api/v1.42.yaml b/api/docs/v1.42.yaml similarity index 100% rename from docs/api/v1.42.yaml rename to api/docs/v1.42.yaml diff --git a/docs/api/v1.43.yaml b/api/docs/v1.43.yaml similarity index 100% rename from docs/api/v1.43.yaml rename to api/docs/v1.43.yaml diff --git a/docs/api/v1.44.yaml b/api/docs/v1.44.yaml similarity index 100% rename from docs/api/v1.44.yaml rename to api/docs/v1.44.yaml diff --git a/docs/api/v1.45.yaml b/api/docs/v1.45.yaml similarity index 100% rename from docs/api/v1.45.yaml rename to api/docs/v1.45.yaml diff --git a/docs/api/v1.46.yaml b/api/docs/v1.46.yaml similarity index 100% rename from docs/api/v1.46.yaml rename to api/docs/v1.46.yaml diff --git a/docs/api/v1.47.yaml b/api/docs/v1.47.yaml similarity index 100% rename from docs/api/v1.47.yaml rename to api/docs/v1.47.yaml diff --git a/docs/api/v1.48.yaml b/api/docs/v1.48.yaml similarity index 100% rename from docs/api/v1.48.yaml rename to api/docs/v1.48.yaml diff --git a/docs/api/v1.49.yaml b/api/docs/v1.49.yaml similarity index 100% rename from docs/api/v1.49.yaml rename to api/docs/v1.49.yaml diff --git a/docs/api/v1.50.yaml b/api/docs/v1.50.yaml similarity index 100% rename from docs/api/v1.50.yaml rename to api/docs/v1.50.yaml diff --git a/docs/api/v1.51.yaml b/api/docs/v1.51.yaml similarity index 100% rename from docs/api/v1.51.yaml rename to api/docs/v1.51.yaml diff --git a/docs/api/README.md b/docs/api/README.md new file mode 100644 index 0000000000..653d5665a1 --- /dev/null +++ b/docs/api/README.md @@ -0,0 +1,4 @@ +# The API documentation has moved + +The API is now implemented in a separate module, and the documentation +has moved to [api/docs](../../api/docs/README.md). diff --git a/vendor/github.com/moby/moby/api/README.md b/vendor/github.com/moby/moby/api/README.md index 381f19881f..f2555794d2 100644 --- a/vendor/github.com/moby/moby/api/README.md +++ b/vendor/github.com/moby/moby/api/README.md @@ -1,4 +1,4 @@ -# Working on the Engine API +# 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. @@ -21,6 +21,7 @@ The API is defined by the [Swagger](http://swagger.io/specification/) definition ## 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. +Documentation for each API version can be found in the [docs directory](docs/README.md), which also provides a [CHANGELOG.md](docs/CHANGELOG.md). The file is split into two main sections: