@@ -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

@@ -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).