add documentation for CustomResourcePublishOpenAPI

content/en/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions.md

@@ -347,6 +347,31 @@ kubectl create -f my-crontab.yaml
 crontab "my-new-cron-object" created
 ```
 
+### Publish Validation Schema in OpenAPI v2
+
+{{< feature-state state="alpha" for_kubernetes_version="1.14" >}}
+
+Starting with Kubernetes 1.14, [custom resource validation schema](#validation) can be published as part
+of [OpenAPI v2 spec](docs/concepts/overview/kubernetes-api.md#openapi-and-swagger-definitions) from
+Kubernetes API server.
+
+The published schema will be consumed by [kubectl](/docs/reference/kubectl/overview) to perform client-side
+validation on custom resources, and can be consumed for other purpose. The feature is disabled by default.
+You can enable the feature using the `CustomResourcePublishOpenAPI` feature gate on the
+[kube-apiserver](/docs/admin/kube-apiserver):
+
+```
+--feature-gates=CustomResourcePublishOpenAPI=true
+```
+
+Custom resource validation schema will be converted to OpenAPI v2 schema, and
+show up in `definitions` and `paths` fields in the OpenAPI spec.
+Additional modification is applied during the conversion to keep backwards compatiblity with
+kubectl in previous 1.13 version. The conversion won't modify the validation schema defined in CRD,
+and therefore won't affect [validation](#validation) in API server. See
+[conversion implementation](https://github.com/kubernetes/kubernetes/blob/83ff0f6c64485ffe491d5116596072f466be1bd5/staging/src/k8s.io/apiextensions-apiserver/pkg/controller/openapi/conversion.go#L42-L112)
+and [compatibility analysis](https://github.com/kubernetes/kube-openapi/pull/143) for detail.
+
 ### Additional printer columns
 
 Starting with Kubernetes 1.11, kubectl uses server-side printing. The server decides which