Make kubectl explain work for Pinniped aggregated APIs

- Change update-codegen.sh script to also generated openapi code for the
  aggregated API types
- Update both aggregated API servers' configuration to make them serve
  the openapi docs for the aggregated APIs
- Add new integration test which runs `kubectl explain` for all Pinniped
  API resources, and all fields and subfields of those resources
- Update some the comments on the API structs
- Change some names of the tmpl files to make the filename better match
  the struct names

apis/concierge/identity/types_whoamirequest.go.tmpl

@@ -17,11 +17,13 @@ type WhoAmIRequest struct {
 	Status WhoAmIRequestStatus
 }
 
+// Spec is always empty for a WhoAmIRequest.
 type WhoAmIRequestSpec struct {
 	// empty for now but we may add some config here in the future
 	// any such config must be safe in the context of an unauthenticated user
 }
 
+// Status is set by the server in the response to a WhoAmIRequest.
 type WhoAmIRequestStatus struct {
 	// The current authenticated user, exactly as Kubernetes understands it.
 	KubernetesUserInfo KubernetesUserInfo
@@ -35,6 +37,6 @@ type WhoAmIRequestList struct {
 	metav1.TypeMeta
 	metav1.ListMeta
 
-	// Items is a list of WhoAmIRequest
+	// Items is a list of WhoAmIRequest.
 	Items []WhoAmIRequest
 }

apis/concierge/identity/v1alpha1/types_whoamirequest.go.tmpl

@@ -20,11 +20,13 @@ type WhoAmIRequest struct {
 	Status WhoAmIRequestStatus `json:"status,omitempty"`
 }
 
+// Spec is always empty for a WhoAmIRequest.
 type WhoAmIRequestSpec struct {
 	// empty for now but we may add some config here in the future
 	// any such config must be safe in the context of an unauthenticated user
 }
 
+// Status is set by the server in the response to a WhoAmIRequest.
 type WhoAmIRequestStatus struct {
 	// The current authenticated user, exactly as Kubernetes understands it.
 	KubernetesUserInfo KubernetesUserInfo `json:"kubernetesUserInfo"`
@@ -38,6 +40,6 @@ type WhoAmIRequestList struct {
 	metav1.TypeMeta `json:",inline"`
 	metav1.ListMeta `json:"metadata,omitempty"`
 
-	// Items is a list of WhoAmIRequest
+	// Items is a list of WhoAmIRequest.
 	Items []WhoAmIRequest `json:"items"`
 }

apis/concierge/login/types_clustercredential.go.tmpl

@@ -5,7 +5,8 @@ package login
 
 import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 
-// ClusterCredential is a credential (token or certificate) which is valid on the Kubernetes cluster.
+// ClusterCredential is the cluster-specific credential returned on a successful credential request. It
+// contains either a valid bearer token or a valid TLS certificate and corresponding private key for the cluster.
 type ClusterCredential struct {
 	// ExpirationTimestamp indicates a time when the provided credentials expire.
 	ExpirationTimestamp metav1.Time

apis/concierge/login/types_tokencredentialrequest.go.tmpl

@@ -8,6 +8,7 @@ import (
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
+// Specification of a TokenCredentialRequest, expected on requests to the Pinniped API.
 type TokenCredentialRequestSpec struct {
 	// Bearer token supplied with the credential request.
 	Token string
@@ -16,8 +17,9 @@ type TokenCredentialRequestSpec struct {
 	Authenticator corev1.TypedLocalObjectReference
 }
 
+// Status of a TokenCredentialRequest, returned on responses to the Pinniped API.
 type TokenCredentialRequestStatus struct {
-	// A ClusterCredential will be returned for a successful credential request.
+	// A Credential will be returned for a successful credential request.
 	// +optional
 	Credential *ClusterCredential
 
@@ -42,6 +44,6 @@ type TokenCredentialRequestList struct {
 	metav1.TypeMeta
 	metav1.ListMeta
 
-	// Items is a list of TokenCredentialRequest
+	// Items is a list of TokenCredentialRequest.
 	Items []TokenCredentialRequest
 }

apis/concierge/login/v1alpha1/types_tokencredentialrequest.go.tmpl

@@ -8,7 +8,7 @@ import (
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
-// TokenCredentialRequestSpec is the specification of a TokenCredentialRequest, expected on requests to the Pinniped API.
+// Specification of a TokenCredentialRequest, expected on requests to the Pinniped API.
 type TokenCredentialRequestSpec struct {
 	// Bearer token supplied with the credential request.
 	Token string `json:"token,omitempty"`
@@ -17,7 +17,7 @@ type TokenCredentialRequestSpec struct {
 	Authenticator corev1.TypedLocalObjectReference `json:"authenticator"`
 }
 
-// TokenCredentialRequestStatus is the status of a TokenCredentialRequest, returned on responses to the Pinniped API.
+// Status of a TokenCredentialRequest, returned on responses to the Pinniped API.
 type TokenCredentialRequestStatus struct {
 	// A Credential will be returned for a successful credential request.
 	// +optional
@@ -47,5 +47,6 @@ type TokenCredentialRequestList struct {
 	metav1.TypeMeta `json:",inline"`
 	metav1.ListMeta `json:"metadata,omitempty"`
 
+	// Items is a list of TokenCredentialRequest.
 	Items []TokenCredentialRequest `json:"items"`
 }

apis/supervisor/clientsecret/types_oidcclientsecretrequest.go.tmpl

@@ -3,44 +3,44 @@
 
 package clientsecret
 
-import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+import (
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
 
-type OIDCClientSecretRequestSpec struct {
-	// Request a new client secret to for the OIDCClient referenced by the metadata.name field.
-	GenerateNewSecret bool `json:"generateNewSecret"`
-
-	// Revoke the old client secrets associated with the OIDCClient referenced by the metadata.name
-	// field.
-	RevokeOldSecrets bool `json:"revokeOldSecrets"`
-}
-
-type OIDCClientSecretRequestStatus struct {
-	// The unencrypted OIDC Client Secret. This will only be shared upon creation and cannot
-	// be recovered if you lose it.
-	GeneratedSecret string `json:"generatedSecret,omitempty"`
-
-	// The total number of client secrets associated with the OIDCClient referenced by the
-	// metadata.name field.
-	TotalClientSecrets int `json:"totalClientSecrets"`
-}
-
-// OIDCClientSecretRequest can be used to update the client secrets associated with an
-// OIDCClient.
+// OIDCClientSecretRequest can be used to update the client secrets associated with an OIDCClient.
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
 type OIDCClientSecretRequest struct {
-	metav1.TypeMeta   `json:",inline"`
-	metav1.ObjectMeta `json:"metadata,omitempty"` // metadata.name must be set to the client ID
+	metav1.TypeMeta
+	metav1.ObjectMeta // metadata.name must be set to the client ID
 
-	Spec   OIDCClientSecretRequestSpec   `json:"spec"`
-	Status OIDCClientSecretRequestStatus `json:"status"`
+	Spec   OIDCClientSecretRequestSpec
+	Status OIDCClientSecretRequestStatus
 }
 
-// OIDCClientSecretList is a list of OIDCClientSecretRequest objects.
+// Spec of the OIDCClientSecretRequest.
+type OIDCClientSecretRequestSpec struct {
+	// Request a new client secret to for the OIDCClient referenced by the metadata.name field.
+	GenerateNewSecret bool
+
+	// Revoke the old client secrets associated with the OIDCClient referenced by the metadata.name field.
+	RevokeOldSecrets bool
+}
+
+// Status of the OIDCClientSecretRequest.
+type OIDCClientSecretRequestStatus struct {
+	// The unencrypted OIDC Client Secret. This will only be shared upon creation and cannot be recovered if lost.
+	GeneratedSecret string
+
+	// The total number of client secrets associated with the OIDCClient referenced by the metadata.name field.
+	TotalClientSecrets int
+}
+
+// OIDCClientSecretRequestList is a list of OIDCClientSecretRequest objects.
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
 type OIDCClientSecretRequestList struct {
 	metav1.TypeMeta
 	metav1.ListMeta
 
-	// Items is a list of OIDCClientSecretRequest
+	// Items is a list of OIDCClientSecretRequest.
 	Items []OIDCClientSecretRequest
 }

apis/supervisor/clientsecret/v1alpha1/types_oidcclientsecretrequest.go.tmpl

@@ -3,18 +3,11 @@
 
 package v1alpha1
 
-import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
-
-type OIDCClientSecretRequestSpec struct {
-	GenerateNewSecret bool `json:"generateNewSecret"`
-	RevokeOldSecrets  bool `json:"revokeOldSecrets"`
-}
-
-type OIDCClientSecretRequestStatus struct {
-	GeneratedSecret    string `json:"generatedSecret,omitempty"`
-	TotalClientSecrets int    `json:"totalClientSecrets"`
-}
+import (
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
 
+// OIDCClientSecretRequest can be used to update the client secrets associated with an OIDCClient.
 // +genclient
 // +genclient:onlyVerbs=create
 // +kubebuilder:subresource:status
@@ -27,10 +20,30 @@ type OIDCClientSecretRequest struct {
 	Status OIDCClientSecretRequestStatus `json:"status"`
 }
 
+// Spec of the OIDCClientSecretRequest.
+type OIDCClientSecretRequestSpec struct {
+	// Request a new client secret to for the OIDCClient referenced by the metadata.name field.
+	GenerateNewSecret bool `json:"generateNewSecret"`
+
+	// Revoke the old client secrets associated with the OIDCClient referenced by the metadata.name field.
+	RevokeOldSecrets bool `json:"revokeOldSecrets"`
+}
+
+// Status of the OIDCClientSecretRequest.
+type OIDCClientSecretRequestStatus struct {
+	// The unencrypted OIDC Client Secret. This will only be shared upon creation and cannot be recovered if lost.
+	GeneratedSecret string `json:"generatedSecret,omitempty"`
+
+	// The total number of client secrets associated with the OIDCClient referenced by the metadata.name field.
+	TotalClientSecrets int `json:"totalClientSecrets"`
+}
+
+// OIDCClientSecretRequestList is a list of OIDCClientSecretRequest objects.
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
 type OIDCClientSecretRequestList struct {
 	metav1.TypeMeta `json:",inline"`
 	metav1.ListMeta `json:"metadata,omitempty"`
 
+	// Items is a list of OIDCClientSecretRequest.
 	Items []OIDCClientSecretRequest `json:"items"`
 }