Related: docker-archive-public/docker.engine-api#77, #5893, #22931

We now have a swagger spec which we use to generate a few types. This issue is to document and track the rest of the required work.

Project

• (Add validate/swagger-gen #28215) add a validate script to check that running the generation does not result in file changes (same idea as validate-vendor)
• (Validation for swagger.yaml #28038) add validation for the swagger.yaml file (see https://github.com/bfirsh/docker-api-reference/blob/master/dobi.yaml) Validation for swagger.yaml #28038
• (Prepare docs and Swagger definition for automatically generated API docs #28506) replace api reference docs with generated docs. See https://github.com/bfirsh/docker-api-reference for a working prototype and Better API and SDKs documentation docker/docs#210 for a WIP PR
• document how contributors can work with the swagger spec and add new types.

Milestone 1 - Types

Generate api/types from the spec:

api/types/types.go

• ContainerChange
• ImageHistory
• ImageDelete
• GraphDriverData
• RootFS
• ImageInspect
• Container
• CopyConfig
• ContainerPathStat
• ContainerStats
• ContainerProcessList
• Version
• Info
• PluginsInfo
• ExecStartCheck
• HealthcheckResult
• Health
• ContainerState
• ContainerNode
• ContainerJSONBase
• ContainerJSON
• NetworkSettings
• SummaryNetworkSettings
• NetworkSettingsBase
• DefaultNetworkSettings
• MountPoint
• NetworkResource
• EndpointResource
• NetworkCreate
• NetworkCreateRequest
• NetworkCreateResponse
• NetworkConnect
• NetworkDisconnect
• Checkpoint
• Runtime
• DiskUsage
• ImagesPruneConfig
• ContainersPruneConfig
• VolumesPruneConfig
• NetworksPruneConfig
• ContainersPruneReport
• VolumesPruneReport
• ImagesPruneReport
• NetworksPruneReport

api/types/swarm/:

• Version
• Meta
• Annotations
• ContainerSpec
• Endpoint
• EndpointSpec
• ResolutionMode
• PortConfig
• PortConfigProtocol
• EndpointVirtualIP
• Network
• NetworkSpec
• NetworkAttachmentConfig
• NetworkAttachment
• IPAMOptions
• IPAMConfig
• Driver
• Node
• NodeSpec
• NodeRole
• NodeAvailability
• NodeDescription
• Platform
• EngineDescription
• PluginDescription
• NodeStatus
• Reachability
• ManagerStatus
• NodeState
• Service
• ServiceSpec
• ServiceMode
• UpdateState
• UpdateStatus
• ReplicatedService
• GlobalService
• UpdateConfig
• ClusterInfo
• Swarm
• JoinTokens
• Spec
• OrchestrationConfig
• TaskDefaults
• RaftConfig
• DispatcherConfig
• CAConfig
• ExternalCAProtocol
• ExternalCAProtocol
• ExternalCA
• InitRequest
• JoinRequest
• LocalNodeState
• Info
• Peer
• UpdateFlags
• TaskState
• Task
• TaskSpec
• Resources
• ResourceRequirements
• Placement
• RestartPolicy
• RestartPolicyCondition
• TaskStatus
• ContainerStatus

Milestone 2 - Client

Generate (most of) client/ from the spec.

This milestone can be done in parallel with Milestone 3, but requires a prototype before work can be enumerated.

Milestone 3 - Server (router)

Generate (most of) api/server/router/ from the spec.

This milestone can be done in parallel with Milestone 2, but requires a prototype before work can be enumerated.