Prepare docs and Swagger definition for automatically generated API docs by bfirsh · Pull Request #28506 · moby/moby

bfirsh · 2016-11-16T21:42:25Z

- What I did

This is some preparation for automatically generating API documentation from a Swagger definition. See #22931.

It is the Engine half of this documentation pull request. This pull request should be merged before the documentation pull request.

It consists of a bunch of things:

Removed the API reference for the latest API version. This is now all in api/swagger.yaml, which the documentation is automatically generated from.
Removed all the other API documentation from this repository. The old versions barely ever change, and all the other stuff is not tied to any code change, so they should probably just live in docker/docker.github.io.
Renamed "Remote API" to "Engine API". See Proposal: Rename "Docker Remote API" to "Docker Engine API" #28319 for details.
Update api/swagger.yaml with some more documentation and some recent API changes.

- A picture of a cute animal (not mandatory but encouraged)

/cc @dnephin @johndmulhausen

johndmulhausen · 2016-11-16T22:38:45Z

So excited about this, thanks @bfirsh. Slowly, we are killing all these hand-rolled markdown files and I couldn't be happier. To be getting such nice-looking API docs is just an added bonus!

cc @mstanleyjones

thaJeztah · 2016-11-17T16:18:52Z

Is there an easy way to generate these docs for preview / reviewing pull requests?

bfirsh · 2016-11-17T16:47:17Z

@thaJeztah I think the easiest way is to copy swagger.yaml into the right place in the documentation repo and run the documentation locally.

That could be documented somewhere I suppose. Perhaps a "API documentation" section in the contributing docs?

dnephin

Some minor requests for changes to OperationID.

Thanks for adding all the missing endpoints.

LGTM

dnephin · 2016-11-17T17:05:42Z

api/swagger.yaml

Could we make this PluginPush ? I've been normalizing everything to be singular.

dnephin · 2016-11-17T17:06:15Z

api/swagger.yaml

ServiceLogs

dnephin · 2016-11-17T17:06:31Z

api/swagger.yaml

SecretList

dnephin · 2016-11-17T17:06:52Z

api/swagger.yaml

SecretCreate

bfirsh · 2016-11-18T13:58:22Z

If we want this included in 1.13, then these changes need cherry-picking to the 1.13 branch. I see no reason why not to include it – it's purely a documentation change.

Following an offline discussion with @thaJeztah, I'm also going to add some docs about how to write and test the API docs.

thaJeztah · 2016-11-18T14:20:51Z

Adding to the milestone, but /cc @vieux

bfirsh · 2016-11-18T18:45:51Z

@thaJeztah @dnephin Documentation added! https://github.com/bfirsh/docker/blob/prepare-api-docs-for-swagger-docs/project/API.md

mdlinville

This is so cool!! Thank you so much, @bfirsh !

See: docker/docs#606 Also: - Add missing redirects to API reference pages - Remove v1.25 and 1.26, because they are being replaced with swagger generated docs. - Remove all other docs which aren't reference material, because this can live in docker/docker.github.io Signed-off-by: Ben Firshman <[email protected]>

Implementation of moby#28319 Signed-off-by: Ben Firshman <[email protected]>

- Tidied up copy - API version is now mandatory - Links to previous API versions Signed-off-by: Ben Firshman <[email protected]>

Up to and including 673c5ee Signed-off-by: Ben Firshman <[email protected]>

thaJeztah

LGTM

mlaventure · 2016-11-22T16:17:34Z

api/README.md

Replace v1.25 with something like <API_VERSION> so we don't have to update this file every release? (we've already updated master to v1.26)

Heh, good point. I'll just remove the version number actually, because /engine/api/ redirects to /engine/api/v1.25/!

@mlaventure Done!

Signed-off-by: Ben Firshman <[email protected]>

vieux · 2016-11-22T21:27:54Z

LGTM

thaJeztah · 2016-11-22T21:47:34Z

There we go!

vieux · 2016-11-23T00:37:54Z

@bfirsh can you create a PR against the 1.13.x branch directly ? this one is tricky to cherry-pick since it's 5 commits and the version changed in master

vieux · 2016-11-23T00:53:47Z

@bfirsh nevermind I got it

bfirsh · 2016-11-23T13:45:18Z

@vieux Nice, thank you! Appreciate that, because I realise it was non-trivial...

vieux · 2016-11-30T00:30:10Z

@bfirsh https://github.com/docker/docker/blob/master/docs/api/version-history.md has 2 broken links, 1.25 and 1.26

bfirsh · 2016-11-30T11:41:59Z

@vieux They will exist once docker/docs#606 exists. :)

Well, 1.26 won't, but the 1.13 branch doesn't have that broken link.

…r-docs Prepare docs and Swagger definition for automatically generated API docs

GordonTheTurtle added the status/0-triage label Nov 16, 2016

bfirsh mentioned this pull request Nov 16, 2016

Automatically generate Engine API documentation docker/docs#606

Merged

bfirsh force-pushed the prepare-api-docs-for-swagger-docs branch from bd08987 to de31a0e Compare November 16, 2016 21:48

thaJeztah added status/1-design-review and removed status/0-triage labels Nov 17, 2016

dnephin mentioned this pull request Nov 17, 2016

Generate API from swagger spec #27919

Open

dnephin reviewed Nov 17, 2016

View reviewed changes

bfirsh force-pushed the prepare-api-docs-for-swagger-docs branch from de31a0e to c794bfe Compare November 18, 2016 13:45

thaJeztah added this to the 1.13.0 milestone Nov 18, 2016

bfirsh force-pushed the prepare-api-docs-for-swagger-docs branch from c794bfe to b728b24 Compare November 18, 2016 18:44

mdlinville approved these changes Nov 18, 2016

View reviewed changes

bfirsh force-pushed the prepare-api-docs-for-swagger-docs branch 4 times, most recently from ef307d0 to 1b1c71b Compare November 21, 2016 15:37

bfirsh added 4 commits November 22, 2016 12:47

Rename Remote API to Engine API

f0d55cd

Implementation of moby#28319 Signed-off-by: Ben Firshman <[email protected]>

Add version information to swagger.yaml

c97f67d

- Tidied up copy - API version is now mandatory - Links to previous API versions Signed-off-by: Ben Firshman <[email protected]>

Update swagger.yaml with changes to API

44c5080

Up to and including 673c5ee Signed-off-by: Ben Firshman <[email protected]>

bfirsh force-pushed the prepare-api-docs-for-swagger-docs branch from 1b1c71b to 00873a9 Compare November 22, 2016 12:49

bfirsh mentioned this pull request Nov 22, 2016

update response status code for cluster request #26576

Merged

bfirsh force-pushed the prepare-api-docs-for-swagger-docs branch from 00873a9 to 79a9ee0 Compare November 22, 2016 14:06

thaJeztah approved these changes Nov 22, 2016

View reviewed changes

thaJeztah added the status/4-merge label Nov 22, 2016

thaJeztah removed the status/1-design-review label Nov 22, 2016

thaJeztah mentioned this pull request Nov 22, 2016

fix doc about service create in docker_remote_api_v1.24.md #28657

Merged

thaJeztah added the process/cherry-pick label Nov 22, 2016

mlaventure suggested changes Nov 22, 2016

View reviewed changes

Add documentation for working on Engine API

109c54c

Signed-off-by: Ben Firshman <[email protected]>

bfirsh force-pushed the prepare-api-docs-for-swagger-docs branch from 79a9ee0 to 109c54c Compare November 22, 2016 16:47

mlaventure approved these changes Nov 22, 2016

View reviewed changes

thaJeztah merged commit 3135024 into moby:master Nov 22, 2016

vieux added process/cherry-picked and removed process/cherry-pick labels Nov 23, 2016

vieux mentioned this pull request Nov 23, 2016

1.13.0-rc2 cherry-picks : part 3 #28674

Merged

bfirsh deleted the prepare-api-docs-for-swagger-docs branch November 30, 2016 11:42

dnephin pushed a commit to dnephin/docker that referenced this pull request Apr 17, 2017

Merge pull request moby#28506 from bfirsh/prepare-api-docs-for-swagge…

36a1664

…r-docs Prepare docs and Swagger definition for automatically generated API docs

Conversation

bfirsh commented Nov 16, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

johndmulhausen commented Nov 16, 2016

Uh oh!

thaJeztah commented Nov 17, 2016

Uh oh!

bfirsh commented Nov 17, 2016

Uh oh!

dnephin left a comment

Choose a reason for hiding this comment

Uh oh!

dnephin Nov 17, 2016

Choose a reason for hiding this comment

Uh oh!

dnephin Nov 17, 2016

Choose a reason for hiding this comment

Uh oh!

dnephin Nov 17, 2016

Choose a reason for hiding this comment

Uh oh!

dnephin Nov 17, 2016

Choose a reason for hiding this comment

Uh oh!

bfirsh commented Nov 18, 2016

Uh oh!

thaJeztah commented Nov 18, 2016

Uh oh!

bfirsh commented Nov 18, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mdlinville left a comment

Choose a reason for hiding this comment

Uh oh!

thaJeztah left a comment

Choose a reason for hiding this comment

Uh oh!

mlaventure Nov 22, 2016

Choose a reason for hiding this comment

Uh oh!

bfirsh Nov 22, 2016

Choose a reason for hiding this comment

Uh oh!

bfirsh Nov 22, 2016

Choose a reason for hiding this comment

Uh oh!

vieux commented Nov 22, 2016

Uh oh!

thaJeztah commented Nov 22, 2016

Uh oh!

vieux commented Nov 23, 2016

Uh oh!

vieux commented Nov 23, 2016

Uh oh!

bfirsh commented Nov 23, 2016

Uh oh!

vieux commented Nov 30, 2016

Uh oh!

bfirsh commented Nov 30, 2016

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

bfirsh commented Nov 16, 2016 •

edited

Loading

bfirsh commented Nov 18, 2016 •

edited

Loading