api: move docs to api module

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

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:
 

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).
+
+

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).

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: