Add make command for previewing API docs

Much easier than the previous method of copying over to the docs
repository and generating the docs.

And, as @cpuguy83 pointed out, that actually didn't work
because the PR that adds Swagger docs isn't merged yet. Oopsy.

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

Makefile

@@ -66,6 +66,8 @@ DOCKER_FLAGS := docker run --rm -i --privileged $(DOCKER_ENVS) $(DOCKER_MOUNT) $
 BUILD_APT_MIRROR := $(if $(DOCKER_BUILD_APT_MIRROR),--build-arg APT_MIRROR=$(DOCKER_BUILD_APT_MIRROR))
 export BUILD_APT_MIRROR
 
+SWAGGER_DOCS_PORT ?= 9000
+
 # if this session isn't interactive, then we don't want to allocate a
 # TTY, which would fail, but if it is interactive, we do want to attach
 # so that the user can send e.g. ^C through.
@@ -156,3 +158,11 @@ swagger-gen:
 		--entrypoint hack/generate-swagger-api.sh \
 		-e GOPATH=/go \
 		quay.io/goswagger/swagger:0.7.4
+
+.PHONY: swagger-docs
+swagger-docs: ## preview the API documentation
+	@echo "API docs preview will be running at http://localhost:$(SWAGGER_DOCS_PORT)"
+	@docker run --rm -v $(PWD)/api/swagger.yaml:/usr/share/nginx/html/swagger.yaml \
+		-e 'REDOC_OPTIONS=hide-hostname="true" lazy-rendering' \
+		-p $(SWAGGER_DOCS_PORT):80 \
+		bfirsh/redoc:1.6.2

api/README.md

@@ -37,6 +37,6 @@ There is hopefully enough example material in the file for you to copy a similar
 
 When you make edits to `swagger.yaml`, you may want to check the generated API documentation to ensure it renders correctly.
 
-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.
+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.
 
-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.
+The production documentation is generated by vendoring `swagger.yaml` into [docker/docker.github.io](https://github.com/docker/docker.github.io).