github.com/zhuohuang-hust/src-cbuild@v0.0.0-20230105071821-c7aab3e7c840/api/README.md (about)

     1  # Working on the Engine API
     2  
     3  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.
     4  
     5  It consists of various components in this repository:
     6  
     7  - `api/swagger.yaml` A Swagger definition of the API.
     8  - `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.
     9  - `cli/` The command-line client.
    10  - `client/` The Go client used by the command-line client. It can also be used by third-party Go programs.
    11  - `daemon/` The daemon, which serves the API.
    12  
    13  ## Swagger definition
    14  
    15  The API is defined by the [Swagger](http://swagger.io/specification/) definition in `api/swagger.yaml`. This definition can be used to:
    16  
    17  1. To automatically generate documentation.
    18  2. To automatically generate the Go server and client. (A work-in-progress.)
    19  3. Provide a machine readable version of the API for introspecting what it can do, automatically generating clients for other languages, etc.
    20  
    21  ## Updating the API documentation
    22  
    23  The API documentation is generated entirely from `api/swagger.yaml`. If you make updates to the API, you'll need to edit this file to represent the change in the documentation.
    24  
    25  The file is split into two main sections:
    26  
    27  - `definitions`, which defines re-usable objects used in requests and responses
    28  - `paths`, which defines the API endpoints (and some inline objects which don't need to be reusable)
    29  
    30  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.
    31  
    32  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)
    33  
    34  `swagger.yaml` is validated by `hack/validate/swagger` to ensure it is a valid Swagger definition. This is useful for when you are making edits to ensure you are doing the right thing.
    35  
    36  ## Viewing the API documentation
    37  
    38  When you make edits to `swagger.yaml`, you may want to check the generated API documentation to ensure it renders correctly.
    39  
    40  All the documentation generation is done in the documentation repository, [docker/docker.github.io](https://github.com/docker/docker.github.io). The Swagger definition is vendored periodically into this repository, but you can manually copy over the Swagger definition to test changes.
    41  
    42  Copy `api/swagger.yaml` in this repository to `engine/api/[VERSION_NUMBER]/swagger.yaml` in the documentation repository, overwriting what is already there. Then, run `docker-compose up` in the documentation repository and browse to [http://localhost:4000/engine/api/](http://localhost:4000/engine/api/) when it finishes rendering.