api/README.md - third_party/docker - Git at Google


            
            # 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.yaml` A 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](https://github.com/docker/docker/issues/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](http://swagger.io/specification/) definition in `api/swagger.yaml`. This definition can be used to:


            1. Automatically generate documentation.

            
            2. Automatically generate the Go server and client. (A work-in-progress.)

            
            3. 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 responses

            
            - `paths`, 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](https://github.com/docker/docker/issues/27919).


            `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](https://github.com/docker/docker.github.io).
	# 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.yaml` A 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](https://github.com/docker/docker/issues/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](http://swagger.io/specification/) definition in `api/swagger.yaml`. This definition can be used to:

	1. Automatically generate documentation.
	2. Automatically generate the Go server and client. (A work-in-progress.)
	3. 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 responses
	- `paths`, 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](https://github.com/docker/docker/issues/27919).

	`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](https://github.com/docker/docker.github.io).