CHANGELOG, cli-reference: update for generate openapi cmd (#1041)

* CHANGELOG.md: add notes on 'generate openapi' and 'add api' updates

* doc/sdk-cli-reference.md: add 'generate openapi' command ref and update 'generate k8s' and 'add api' refs

Author: estroz

CHANGELOG.md

@@ -7,6 +7,8 @@
 - By default the controller-runtime metrics are exposed on port 8383. This is done as part of the scaffold in the main.go file, the port can be adjusted by modifying the `metricsPort` variable. [#786](https://github.com/operator-framework/operator-sdk/pull/786)
 - A new command [`operator-sdk olm-catalog`](https://github.com/operator-framework/operator-sdk/blob/master/doc/sdk-cli-reference.md#olm-catalog) to be used as a parent for SDK subcommands generating code related to Operator Lifecycle Manager (OLM) Catalog integration, and subcommand [`operator-sdk olm-catalog gen-csv`](https://github.com/operator-framework/operator-sdk/blob/master/doc/sdk-cli-reference.md#gen-csv) which generates a Cluster Service Version for an operator so the OLM can deploy the operator in a cluster. ([#673](https://github.com/operator-framework/operator-sdk/pull/673))
 - Helm-based operators have leader election turned on by default. When upgrading, add environment variable `POD_NAME` to your operator's Deployment using the Kubernetes downward API. To see an example, run `operator-sdk new --type=helm ...` and see file `deploy/operator.yaml`. [#1000](https://github.com/operator-framework/operator-sdk/pull/1000)
+- A new command [`operator-sdk generate openapi`](https://github.com/operator-framework/operator-sdk/blob/master/doc/sdk-cli-reference.md#openapi) which generates OpenAPIv3 validation specs in Go and in CRD manifests as YAML. ([#869](https://github.com/operator-framework/operator-sdk/pull/869))
+- The `operator-sdk add api` command now generates OpenAPIv3 validation specs in Go for that API, and in all CRD manifests as YAML.
 
 ### Changed
 

doc/sdk-cli-reference.md

@@ -133,8 +133,8 @@ pkg/apis/app/v1alpha1/
 ├── register.go
 
 $ operator-sdk generate k8s
-Running code-generation for custom resource group versions: [app:v1alpha1]
-Generating deepcopy funcs
+INFO[0000] Running deepcopy code-generation for Custom Resource group versions: [app:[v1alpha1], ]
+INFO[0001] Code-generation complete.                    
 
 $ tree pkg/apis/app/v1alpha1/
 pkg/apis/app/v1alpha1/
@@ -144,6 +144,34 @@ pkg/apis/app/v1alpha1/
 └── zz_generated.deepcopy.go
 ```
 
+### openapi
+
+Runs the [kube-openapi][openapi-code-generator] OpenAPIv3 code generator for all Custom Resource Definition (CRD) API tagged fields under `pkg/apis/...`.
+
+**Note**: This command must be run every time a tagged API struct or struct field for a custom resource type is updated.
+
+#### Example
+
+```console
+$ tree pkg/apis/app/v1alpha1/
+pkg/apis/app/v1alpha1/
+├── appservice_types.go
+├── doc.go
+├── register.go
+
+$ operator-sdk generate openapi
+INFO[0000] Running OpenAPI code-generation for Custom Resource group versions: [app:[v1alpha1], ]
+INFO[0001] Create deploy/crds/app_v1alpha1_appservice_crd.yaml
+INFO[0001] Code-generation complete.                    
+
+$ tree pkg/apis/app/v1alpha1/
+pkg/apis/app/v1alpha1/
+├── appservice_types.go
+├── doc.go
+├── register.go
+└── zz_generated.openapi.go
+```
+
 ## olm-catalog
 
 Parent command for all OLM Catalog related commands.
@@ -237,7 +265,7 @@ $ operator-sdk new app-operator --type=helm --api-version=app.example.com/v1alph
 
 ### api
 
-Adds the api definition for a new custom resource under `pkg/apis` and generates the CRD and CR files under `depoy/crds/...`.
+Adds the API definition for a new custom resource under `pkg/apis` and generates the CRD and CR files under `depoy/crds/...`, and generates Kubernetes deepcopy functions and OpenAPIv3 validation specs for the new API.
 
 #### Flags
 
@@ -248,14 +276,19 @@ Adds the api definition for a new custom resource under `pkg/apis` and generates
 
 ```console
 $ operator-sdk add api --api-version app.example.com/v1alpha1 --kind AppService
-Create pkg/apis/app/v1alpha1/appservice_types.go
-Create pkg/apis/addtoscheme_app_v1alpha1.go
-Create pkg/apis/app/v1alpha1/register.go
-Create pkg/apis/app/v1alpha1/doc.go
-Create deploy/crds/app_v1alpha1_appservice_cr.yaml
-Create deploy/crds/app_v1alpha1_appservice_crd.yaml
-Running code-generation for custom resource group versions: [app:v1alpha1]
-Generating deepcopy funcs
+INFO[0000] Generating api version app.example.com/v1alpha1 for kind AppService.
+INFO[0000] Create pkg/apis/app/v1alpha1/appservice_types.go
+INFO[0000] Create pkg/apis/addtoscheme_app_v1alpha1.go  
+INFO[0000] Create pkg/apis/app/v1alpha1/register.go     
+INFO[0000] Create pkg/apis/app/v1alpha1/doc.go          
+INFO[0000] Create deploy/crds/app_v1alpha1_appservice_cr.yaml
+INFO[0000] Create deploy/crds/app_v1alpha1_appservice_crd.yaml
+INFO[0001] Running deepcopy code-generation for Custom Resource group versions: [app:[v1alpha1], ]
+INFO[0002] Code-generation complete.                    
+INFO[0002] Running OpenAPI code-generation for Custom Resource group versions: [app:[v1alpha1], ]
+INFO[0004] Create deploy/crds/app_v1alpha1_appservice_crd.yaml
+INFO[0004] Code-generation complete.                    
+INFO[0004] API generation complete.
 ```
 
 ### controller
@@ -490,3 +523,4 @@ $ operator-sdk up local --namespace "testing"
 
 [utility_link]: https://github.com/operator-framework/operator-sdk/blob/89bf021063d18b6769bdc551ed08fc37027939d5/pkg/util/k8sutil/k8sutil.go#L140
 [k8s-code-generator]: https://github.com/kubernetes/code-generator
+[openapi-code-generator]: https://github.com/kubernetes/kube-openapi