Automatically generate Engine API documentation #606

bfirsh · 2016-11-16T21:32:40Z

I have replaced the Engine API docs with a version that is automatically generated from a Swagger definition, using ReDoc. It looks a bit like this:

I have also reorganised the menu for the Engine API to make it simpler and clearer:

Before, it was under "reference", even though some of it wasn't reference material, and it also seemed quite hidden that deep in the menu tree.

I've done a few other things, too:

Tidied up some URLs (removed superfluous words, s/_/-/, etc)
Moved the accounts API documentation the Docker Hub section. It makes more sense here than the Engine reference, I think – the Hub serves the API, the Engine consumes it.
Rename Remote API to Engine API. See Proposal: Rename "Docker Remote API" to "Docker Engine API" moby/moby#28319 for details.

Known issues

ReDoc is a client-side app that takes a bit of time to load. The author is working on a fix and I think the downside of this outweighs the benefit of much better documentation.

Related issues

This vendors swagger.yaml from this Engine change: Prepare docs and Swagger definition for automatically generated API docs moby/moby#28506. It would probably be worth waiting until that is merged so we can be sure we're vendoring the correct thing.
This is a subset of Better API and SDKs documentation #210. Just the API docs, and none of the additional SDK docs. As discussed with @johndmulhausen, this seemed like a much less controversial subset that we could get in to start with.
Background on Swagger definition: Generate API from swagger spec moby/moby#27919
Closes Feature/betterment of people's lives: Generated docs moby/moby#22931

/cc @dnephin @johndmulhausen

johndmulhausen · 2016-11-16T21:39:00Z

Deploy preview ready!

Built with commit 007d0a5

https://deploy-preview-606--docker-docs.netlify.com

sanscontext · 2016-11-16T21:59:27Z

Noting an offline discussion: the accounts apis touch more than Hub, currently in discussion about where they ought to go. :)

johndmulhausen · 2016-11-17T01:42:49Z

@sanscontext @mstanleyjones @londoncalling @joaofnfernandes

The most relevant staging URL is here:
https://deploy-preview-606--docker-docs.netlify.com/engine/api/v1.25/

Be aware that this PR also changes "Remote API" to "Engine API" so make sure any find/replaces were done right

johndmulhausen · 2016-11-17T22:26:21Z

@bfirsh Can you make the links to API versions relative instead of https://docs.docker.com ? E.g. have the URLs just be /engine/api/v1.24/ with no domain. That way they'll show the version that is shipping with that branch/fork/clone of the docs

https://deploy-preview-606--docker-docs.netlify.com/engine/api/v1.25/#section/Versioning

Clicking on these now, you can see that they 404

johndmulhausen · 2016-11-17T23:27:07Z

Other than that, this LGTM!

sanscontext · 2016-11-17T23:40:11Z

Can we hold off on merge until I've got a Docker ID stub in place to rehome the Hub docs?

sanscontext · 2016-11-18T01:45:23Z

Please hold off until #634 has merged.

bfirsh · 2016-11-18T13:32:10Z

@johndmulhausen Okay. That was intentional so the swagger.yaml would work standalone, but I guess it's not the end of the world making the intro description just work inside the documentation.

johndmulhausen · 2016-11-18T22:27:03Z

@bfirsh Belay my comment then; I get it.

johndmulhausen · 2016-11-18T22:50:21Z

@bfirsh PR #634 has been merged and it makes sense to have the Accounts API reference live under /docker-id/ -- can you update this PR?

I suggest /docker-id/api-reference/

bfirsh · 2016-11-21T13:56:37Z

Due to #511, we're now going to have to wait for moby/moby#28506 to make its way into the 1.12 branch. I will push this along. :)

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 <ben@firshman.co.uk>

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 <ben@firshman.co.uk> (cherry picked from commit 993854f) Signed-off-by: Victor Vieux <victorvieux@gmail.com>

bfirsh · 2016-11-23T13:48:41Z

moby/moby#28506 is now merged. 🎉

I'll wait for #674 before updating this PR.

bfirsh · 2016-11-24T17:49:14Z

@mstanleyjones @johndmulhausen This is also just for Docker 1.13, so presumably I should open it against the branch vnext-engine? Will #511 be cherry-picked into that branch?

bfirsh · 2016-11-25T13:09:02Z

Okay, I have now implemented this PR on top of #511 and #674. The implementation is ready for review, apart from the hacks in Dockerfile to pull from the correct Docker version.

Once #511 and #674 have made their way into the vnext-engine branch, I can switch this PR to that branch and it should be ready to merge.

This makes the swagger.yaml useful outside of the documentation. For background: docker/docs#606 (comment) Signed-off-by: Ben Firshman <ben@firshman.co.uk>

johndmulhausen · 2016-11-28T21:19:52Z

@bfirsh Everything in master will be merged into vnext-engine so yes, #511 and every other fix that's happened here will be pulled in. :) As for which branch to open this PR against, yes -- if it's for v1.13 only, you want to do that against vnext-engine. Which means you might have to create a new PR for this.

bfirsh · 2016-11-29T17:33:39Z

Looks like #734 includes #511 and #674, so I will wait for that before switching branches.

And yes – this is v1.13 only.

This makes the swagger.yaml useful outside of the documentation. For background: docker/docs#606 (comment) Signed-off-by: Ben Firshman <ben@firshman.co.uk> (cherry picked from commit 54051b1) Signed-off-by: Victor Vieux <victorvieux@gmail.com>

mdlinville · 2016-12-01T01:41:49Z

You'll now want to look at #756, though that's only there for audit purposes. If @thaJeztah approves it I will force-push vnext-engine to that state, which is the 21 patches in vnext-engine rebased on master. It's ugly, but trying to do a merge was too complicated.

johndmulhausen · 2016-12-07T11:22:47Z

@bfirsh Where are we on this? Do you plan to shut this PR down and make a new one pointed at vnext-engine? According to the Netlify staging, ReDoc isn't getting a swagger spec anymore

bfirsh · 2016-12-08T13:45:42Z

@johndmulhausen Yep! Just waiting for vnext-engine to be rebased and I'll sort it out.

I'm not really keeping a close eye on that, so feel free to ping me on here when I need to my bit.

mdlinville · 2016-12-09T17:22:13Z

@bfirsh this should be good to go after you rebase on current vnext-engine to resolve the conflict. I did the force-push this morning.

Makes more sense here instead of the Engine reference. It is only consumed by the Engine. Signed-off-by: Ben Firshman <ben@firshman.co.uk>

See moby/moby#28319 Signed-off-by: Ben Firshman <ben@firshman.co.uk>

Signed-off-by: Ben Firshman <ben@firshman.co.uk>

johndmulhausen · 2016-12-14T00:03:06Z

bfirsh · 2016-12-14T11:40:44Z

Oh nice - thanks! Glad that just worked. 💃

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 <ben@firshman.co.uk>

This makes the swagger.yaml useful outside of the documentation. For background: docker/docs#606 (comment) Signed-off-by: Ben Firshman <ben@firshman.co.uk>

bfirsh mentioned this pull request Nov 16, 2016

Feature/betterment of people's lives: Generated docs moby/moby#22931

Closed

bfirsh mentioned this pull request Nov 16, 2016

Prepare docs and Swagger definition for automatically generated API docs moby/moby#28506

Merged

bfirsh force-pushed the swagger-api-docs branch from 508001e to 89e0467 Compare November 16, 2016 21:48

bfirsh force-pushed the swagger-api-docs branch from 89e0467 to c3f87ac Compare November 16, 2016 22:06

johndmulhausen mentioned this pull request Nov 18, 2016

Meta Docker ID topic #634

Merged

bfirsh force-pushed the swagger-api-docs branch 2 times, most recently from b561355 to 4843cf9 Compare November 25, 2016 13:05

bfirsh mentioned this pull request Nov 25, 2016

Updates to swagger.yaml and API documentation moby/moby#28840

Merged

bfirsh added a commit to bfirsh/docker that referenced this pull request Nov 28, 2016

Make docs URLs in swagger.yaml absolute

54051b1

This makes the swagger.yaml useful outside of the documentation. For background: docker/docs#606 (comment) Signed-off-by: Ben Firshman <ben@firshman.co.uk>

This was referenced Nov 29, 2016

api changes links not working #677

Closed

Feedback for: engine/reference/api/docker_remote_api_v1.24.md #666

Closed

Feedback for: engine/reference/api/docker_remote_api.md Request for linkback to getting started with Docker Remote API #690

Closed

johndmulhausen assigned johndmulhausen and mdlinville Nov 29, 2016

bfirsh mentioned this pull request Dec 1, 2016

Vnext engine rebase #756

Closed

bfirsh force-pushed the swagger-api-docs branch from 4843cf9 to 007d0a5 Compare December 1, 2016 11:32

bfirsh mentioned this pull request Dec 1, 2016

Better API and SDKs documentation #210

Merged

5 tasks

mdlinville changed the base branch from master to vnext-engine December 13, 2016 22:57

mdlinville force-pushed the swagger-api-docs branch from 007d0a5 to ed9ff27 Compare December 13, 2016 22:58

bfirsh added 3 commits December 13, 2016 15:43

Move accounts API docs to Docker ID section

2c17f9e

Makes more sense here instead of the Engine reference. It is only consumed by the Engine. Signed-off-by: Ben Firshman <ben@firshman.co.uk>

Rename Remote API to Engine API

f770515

See moby/moby#28319 Signed-off-by: Ben Firshman <ben@firshman.co.uk>

Add automatically generated Engine API docs

bb3423a

Signed-off-by: Ben Firshman <ben@firshman.co.uk>

mdlinville force-pushed the swagger-api-docs branch from ed9ff27 to bb3423a Compare December 13, 2016 23:58

mdlinville requested a review from johndmulhausen December 13, 2016 23:58

johndmulhausen approved these changes Dec 14, 2016

View reviewed changes

mdlinville merged commit 387dc47 into docker:vnext-engine Dec 14, 2016

bfirsh deleted the swagger-api-docs branch December 15, 2016 15:15

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Automatically generate Engine API documentation #606

Automatically generate Engine API documentation #606

bfirsh commented Nov 16, 2016 •

edited

Loading

johndmulhausen commented Nov 16, 2016 •

edited

Loading

sanscontext commented Nov 16, 2016

johndmulhausen commented Nov 17, 2016

johndmulhausen commented Nov 17, 2016 •

edited

Loading

johndmulhausen commented Nov 17, 2016

sanscontext commented Nov 17, 2016

sanscontext commented Nov 18, 2016

bfirsh commented Nov 18, 2016

johndmulhausen commented Nov 18, 2016

johndmulhausen commented Nov 18, 2016 •

edited

Loading

bfirsh commented Nov 21, 2016

bfirsh commented Nov 23, 2016

bfirsh commented Nov 24, 2016 •

edited

Loading

bfirsh commented Nov 25, 2016

johndmulhausen commented Nov 28, 2016

bfirsh commented Nov 29, 2016

mdlinville commented Dec 1, 2016

johndmulhausen commented Dec 7, 2016

bfirsh commented Dec 8, 2016 •

edited

Loading

mdlinville commented Dec 9, 2016

johndmulhausen commented Dec 14, 2016

bfirsh commented Dec 14, 2016

Automatically generate Engine API documentation #606

Automatically generate Engine API documentation #606

Conversation

bfirsh commented Nov 16, 2016 • edited Loading

Known issues

Related issues

johndmulhausen commented Nov 16, 2016 • edited Loading

sanscontext commented Nov 16, 2016

johndmulhausen commented Nov 17, 2016

johndmulhausen commented Nov 17, 2016 • edited Loading

johndmulhausen commented Nov 17, 2016

sanscontext commented Nov 17, 2016

sanscontext commented Nov 18, 2016

bfirsh commented Nov 18, 2016

johndmulhausen commented Nov 18, 2016

johndmulhausen commented Nov 18, 2016 • edited Loading

bfirsh commented Nov 21, 2016

bfirsh commented Nov 23, 2016

bfirsh commented Nov 24, 2016 • edited Loading

bfirsh commented Nov 25, 2016

johndmulhausen commented Nov 28, 2016

bfirsh commented Nov 29, 2016

mdlinville commented Dec 1, 2016

johndmulhausen commented Dec 7, 2016

bfirsh commented Dec 8, 2016 • edited Loading

mdlinville commented Dec 9, 2016

johndmulhausen commented Dec 14, 2016

bfirsh commented Dec 14, 2016

bfirsh commented Nov 16, 2016 •

edited

Loading

johndmulhausen commented Nov 16, 2016 •

edited

Loading

johndmulhausen commented Nov 17, 2016 •

edited

Loading

johndmulhausen commented Nov 18, 2016 •

edited

Loading

bfirsh commented Nov 24, 2016 •

edited

Loading

bfirsh commented Dec 8, 2016 •

edited

Loading