Add openapi support, and generate the specifications.

Makefile

@@ -11,7 +11,7 @@ PROJECT = github.com/weaveworks/ignite
 APIS_DIR = ${PROJECT}/pkg/apis
 API_DIRS = ${APIS_DIR}/ignite/v1alpha1,${APIS_DIR}/meta/v1alpha1
 CACHE_DIR = $(shell pwd)/bin/cache
-API_DOCS = docs/api-reference/ignite.md docs/api-reference/meta.md
+API_DOCS = api/ignite.md api/meta.md
 
 all: binary
 binary:
@@ -49,7 +49,7 @@ tidy: $(API_DOCS)
 	go run hack/cobra.go
 
 .PHONY: $(API_DOCS)
-$(API_DOCS): docs/api-reference/%.md: $(CACHE_DIR)/go/bin/godoc2md
+$(API_DOCS): api/%.md: $(CACHE_DIR)/go/bin/godoc2md
 	mkdir -p $$(dirname $@) bin/tmp/$*
 	mv $(shell pwd)/pkg/apis/$*/v1alpha1/zz_generated* bin/tmp/$*
 	$(MAKE) shell COMMAND="/go/bin/godoc2md /go/src/${PROJECT}/pkg/apis/$*/v1alpha1 > $@"
@@ -65,8 +65,8 @@ shell:
 	docker run -it --rm \
 		-v $(CACHE_DIR)/go:/go \
 		-v $(CACHE_DIR)/cache:/.cache/go-build \
-		-v $(shell pwd):/go/src/github.com/weaveworks/ignite \
-		-w /go/src/github.com/weaveworks/ignite \
+		-v $(shell pwd):/go/src/${PROJECT} \
+		-w /go/src/${PROJECT} \
 		-u $(shell id -u):$(shell id -g) \
 		-e GO111MODULE=on \
 		golang:$(GO_VERSION) \
@@ -75,7 +75,7 @@ shell:
 autogen:
 	$(MAKE) shell COMMAND="make dockerized-autogen"
 
-dockerized-autogen: /go/bin/deepcopy-gen /go/bin/defaulter-gen /go/bin/conversion-gen
+dockerized-autogen: /go/bin/deepcopy-gen /go/bin/defaulter-gen /go/bin/conversion-gen /go/bin/openapi-gen
 	# Let the boilerplate be empty
 	touch /tmp/boilerplate
 	/go/bin/deepcopy-gen \
@@ -93,6 +93,15 @@ dockerized-autogen: /go/bin/deepcopy-gen /go/bin/defaulter-gen /go/bin/conversio
 		--input-dirs ${API_DIRS} \
 		-O zz_generated.conversion \
 		-h /tmp/boilerplate
+
+	/go/bin/openapi-gen \
+		--input-dirs ${API_DIRS} \
+		--output-package ${PROJECT}/api/openapi \
+		--report-filename api/openapi/violations.txt \
+		-h /tmp/boilerplate
 
 /go/bin/%: vendor
 	go install k8s.io/code-generator/cmd/$*
+
+/go/bin/openapi-gen:
+	go install k8s.io/kube-openapi/cmd/openapi-gen

api/README.md

@@ -0,0 +1,15 @@
+## Ignite API
+
+The Ignite API types use the [`k8s.io/apimachinery`](https://github.com/kubernetes/apimachinery) framework, and
+similar conventions as the Kubernetes API types. That said, the Ignite API types don't (at the moment at least)
+have any connection or depend on Kubernetes itself in any way.
+
+The API types are used for two primary things:
+
+ - Letting end users [declaratively specify advanced configuration](../docs/declarative-config.md) (e.g. `ignite create --config`)
+ - Persisting internal data on disk in a standardized way.
+
+Please refer to the (autogenerated) docs for the API types:
+
+ - `ignite.weave.works/v1alpha1` in [ignite.md](ignite.md)
+ - The meta-package containing generic types [meta.md](meta.md)