summarize schema customization in kube-derive docs

Author: clux

kube-derive/src/lib.rs

@@ -70,7 +70,7 @@ mod custom_resource;
 ///
 /// ### `#[kube(apiextensions = "v1beta1")]`
 /// The version for `CustomResourceDefinition` desired in the `apiextensions.k8s.io` group.
-/// Default is `v1` (for clusters >= 1.17). If using kubernetes <= 1.16 pluase use `v1beta1`.
+/// Default is `v1` (for clusters >= 1.17). If using kubernetes <= 1.16 please use `v1beta1`.
 ///
 /// **NOTE**: Support for `v1` requires deriving the openapi v3 `JsonSchema` via the `schemars` dependency.
 ///
@@ -150,6 +150,18 @@ mod custom_resource;
 /// }
 /// ```
 ///
+/// ## Customizing Schemas
+/// Should you need to customize the schemas, you can use:
+/// - [Serde/Schemars Attributes](https://graham.cool/schemars/examples/3-schemars_attrs/) (no need to duplicate serde renames)
+/// - [`#[schemars(schema_with = "func")]`](https://graham.cool/schemars/examples/7-custom_serialization/) (e.g. like in the [`crd_derive` example](https://github.com/clux/kube-rs/blob/master/examples/crd_derive.rs))
+///
+/// In general, you will need to override parts of the schemas (for fields in question) when you are:
+/// - **using enums**: enums do not currently generate [structural schemas](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#specifying-a-structural-schema), so kubernetes won't support them by default
+/// - **customizing [merge-strategies](https://kubernetes.io/docs/reference/using-api/server-side-apply/#merge-strategy)** (e.g. like in the [`crd_derive_schema` example](https://github.com/clux/kube-rs/blob/master/examples/crd_derive_schema.rs))
+/// - **customizing [certain kubebuilder like validation rules](https://github.com/clux/kube-rs/issues/129#issuecomment-749463718)** (tail the issue for state of affairs)
+///
+/// If you have to override a lot, [you can opt-out of schema-generation entirely](https://github.com/clux/kube-rs/issues/355#issuecomment-751253657)
+///
 /// ## Debugging
 /// Try `cargo-expand` to see your own macro expansion.
 ///

kube/src/api/params.rs

@@ -150,8 +150,8 @@ impl PostParams {
 ///
 /// See [kubernetes patch docs](https://kubernetes.io/docs/tasks/run-application/update-api-object-kubectl-patch/#use-a-json-merge-patch-to-update-a-deployment) for the older patch types.
 ///
-/// Note that patches have different effects on different fields depending on their [merge-strategies](https://kubernetes.io/docs/reference/using-api/server-side-apply/#merge-strategy).
-/// These strategies are configurable when deriving your [`CustomResource`](kube_derive::CustomResource).
+/// Note that patches have different effects on different fields depending on their merge strategies.
+/// These strategies are configurable when deriving your [`CustomResource`](kube_derive::CustomResource#customizing-schemas).
 ///
 /// # Creating a patch via serde_json
 /// ```