Add OpenAPI README file

api/openapi-spec/README.md

+# Kubernetes's OpenAPI Specification
+
+This folder contains an [OpenAPI specification][openapi] for Kubernetes API.
+
+## Vendor Extensions
+
+Kuberntes extends OpenAPI using these extensions. Note the version that 
+extensions has been added.
+
+### `x-kubernetes-group-version-kind`
+
+Operations and Definitions may have `x-kubernetes-group-version-kind` if they
+are associated with a [kubernetes resource](https://github.com/kubernetes/community/blob/master/contributors/devel/api-conventions.md#resources).
+
+
+For example:
+
+``` json
+"paths": {
+    ...
+    "/api/v1/namespaces/{namespace}/pods/{name}": {
+        ...
+        "get": {
+        ...
+            "x-kubernetes-group-version-kind": {
+            "group": "",
+            "version": "v1",
+            "kind": "Pod"
+            }
+        }
+    }
+}
+```
+
+### `x-kubernetes-action`
+
+Operations and Definitions may have `x-kubernetes-action` if they
+are associated with a [kubernetes resource](https://github.com/kubernetes/community/blob/master/contributors/devel/api-conventions.md#resources).
+Action can be one of `get`, `list`, `put`, `patch`, `post`, `delete`, `deletecollection`, `watch`, `watchlist`, `proxy`, or `connect`.
+
+
+For example:
+
+``` json
+"paths": {
+    ...
+    "/api/v1/namespaces/{namespace}/pods/{name}": {
+        ...
+        "get": {
+        ...
+            "x-kubernetes-action": "list"
+        }
+    }
+}
+```
+
+### `x-kubernetes-patch-strategy` and `x-kubernetes-patch-merge-key`
+
+Some of the definitions may have these extensions. For more information about PatchStrategy and PatchMergeKey see 
+[strategic-merge-patch] (https://github.com/kubernetes/community/blob/3a1e6d22f812751ee88eccf7c59101852de63d5b/contributors/devel/strategic-merge-patch.md).

hack/verify-openapi-spec.sh

@@ -36,6 +36,7 @@ cp -a "${SPECROOT}" "${TMP_SPECROOT}"
 trap "cp -a ${TMP_SPECROOT} ${SPECROOT}/..; rm -rf ${_tmp}" EXIT SIGINT
 rm ${SPECROOT}/*
 cp ${TMP_SPECROOT}/BUILD ${SPECROOT}/BUILD 
+cp ${TMP_SPECROOT}/README.md ${SPECROOT}/README.md
 
 "${KUBE_ROOT}/hack/update-openapi-spec.sh"
 echo "diffing ${SPECROOT} against freshly generated openapi spec"