Add missing comments in APF API types

api/openapi-spec/swagger.json

@@ -11098,17 +11098,20 @@
       "description": "Subject matches the originator of a request, as identified by the request authentication system. There are three ways of matching an originator; by user, group, or service account.",
       "properties": {
         "group": {
-          "$ref": "#/definitions/io.k8s.api.flowcontrol.v1beta1.GroupSubject"
+          "$ref": "#/definitions/io.k8s.api.flowcontrol.v1beta1.GroupSubject",
+          "description": "`group` matches based on user group name."
         },
         "kind": {
-          "description": "Required",
+          "description": "`kind` indicates which one of the other fields is non-empty. Required",
           "type": "string"
         },
         "serviceAccount": {
-          "$ref": "#/definitions/io.k8s.api.flowcontrol.v1beta1.ServiceAccountSubject"
+          "$ref": "#/definitions/io.k8s.api.flowcontrol.v1beta1.ServiceAccountSubject",
+          "description": "`serviceAccount` matches ServiceAccounts."
         },
         "user": {
-          "$ref": "#/definitions/io.k8s.api.flowcontrol.v1beta1.UserSubject"
+          "$ref": "#/definitions/io.k8s.api.flowcontrol.v1beta1.UserSubject",
+          "description": "`user` matches based on username."
         }
       },
       "required": [

hack/.descriptions_failures

@@ -4,7 +4,5 @@
 ./staging/src/k8s.io/api/certificates/v1/types.go
 ./staging/src/k8s.io/api/certificates/v1beta1/types.go
 ./staging/src/k8s.io/api/core/v1/types.go
-./staging/src/k8s.io/api/flowcontrol/v1alpha1/types.go
-./staging/src/k8s.io/api/flowcontrol/v1beta1/types.go
 ./staging/src/k8s.io/api/networking/v1/types.go
 ./staging/src/k8s.io/api/networking/v1beta1/types.go

pkg/apis/flowcontrol/types.go

@@ -171,13 +171,17 @@ type PolicyRulesWithSubjects struct {
 // ways of matching an originator; by user, group, or service account.
 // +union
 type Subject struct {
+	// `kind` indicates which one of the other fields is non-empty.
 	// Required
 	// +unionDiscriminator
 	Kind SubjectKind
+	// `user` matches based on username.
 	// +optional
 	User *UserSubject
+	// `group` matches based on user group name.
 	// +optional
 	Group *GroupSubject
+	// `serviceAccount` matches ServiceAccounts.
 	// +optional
 	ServiceAccount *ServiceAccountSubject
 }

staging/src/k8s.io/api/flowcontrol/v1alpha1/generated.proto

@@ -411,16 +411,20 @@ message ServiceAccountSubject {
 // ways of matching an originator; by user, group, or service account.
 // +union
 message Subject {
+  // `kind` indicates which one of the other fields is non-empty.
   // Required
   // +unionDiscriminator
   optional string kind = 1;
 
+  // `user` matches based on username.
   // +optional
   optional UserSubject user = 2;
 
+  // `group` matches based on user group name.
   // +optional
   optional GroupSubject group = 3;
 
+  // `serviceAccount` matches ServiceAccounts.
   // +optional
   optional ServiceAccountSubject serviceAccount = 4;
 }

staging/src/k8s.io/api/flowcontrol/v1alpha1/types.go

@@ -185,13 +185,17 @@ type PolicyRulesWithSubjects struct {
 // ways of matching an originator; by user, group, or service account.
 // +union
 type Subject struct {
+	// `kind` indicates which one of the other fields is non-empty.
 	// Required
 	// +unionDiscriminator
 	Kind SubjectKind `json:"kind" protobuf:"bytes,1,opt,name=kind"`
+	// `user` matches based on username.
 	// +optional
 	User *UserSubject `json:"user,omitempty" protobuf:"bytes,2,opt,name=user"`
+	// `group` matches based on user group name.
 	// +optional
 	Group *GroupSubject `json:"group,omitempty" protobuf:"bytes,3,opt,name=group"`
+	// `serviceAccount` matches ServiceAccounts.
 	// +optional
 	ServiceAccount *ServiceAccountSubject `json:"serviceAccount,omitempty" protobuf:"bytes,4,opt,name=serviceAccount"`
 }

staging/src/k8s.io/api/flowcontrol/v1alpha1/types_swagger_doc_generated.go

@@ -238,8 +238,11 @@ func (ServiceAccountSubject) SwaggerDoc() map[string]string {
 }
 
 var map_Subject = map[string]string{
-	"":     "Subject matches the originator of a request, as identified by the request authentication system. There are three ways of matching an originator; by user, group, or service account.",
-	"kind": "Required",
+	"":               "Subject matches the originator of a request, as identified by the request authentication system. There are three ways of matching an originator; by user, group, or service account.",
+	"kind":           "`kind` indicates which one of the other fields is non-empty. Required",
+	"user":           "`user` matches based on username.",
+	"group":          "`group` matches based on user group name.",
+	"serviceAccount": "`serviceAccount` matches ServiceAccounts.",
 }
 
 func (Subject) SwaggerDoc() map[string]string {

staging/src/k8s.io/api/flowcontrol/v1beta1/generated.proto

@@ -411,16 +411,20 @@ message ServiceAccountSubject {
 // ways of matching an originator; by user, group, or service account.
 // +union
 message Subject {
+  // `kind` indicates which one of the other fields is non-empty.
   // Required
   // +unionDiscriminator
   optional string kind = 1;
 
+  // `user` matches based on username.
   // +optional
   optional UserSubject user = 2;
 
+  // `group` matches based on user group name.
   // +optional
   optional GroupSubject group = 3;
 
+  // `serviceAccount` matches ServiceAccounts.
   // +optional
   optional ServiceAccountSubject serviceAccount = 4;
 }

staging/src/k8s.io/api/flowcontrol/v1beta1/types.go

@@ -223,13 +223,17 @@ type PolicyRulesWithSubjects struct {
 // ways of matching an originator; by user, group, or service account.
 // +union
 type Subject struct {
+	// `kind` indicates which one of the other fields is non-empty.
 	// Required
 	// +unionDiscriminator
 	Kind SubjectKind `json:"kind" protobuf:"bytes,1,opt,name=kind"`
+	// `user` matches based on username.
 	// +optional
 	User *UserSubject `json:"user,omitempty" protobuf:"bytes,2,opt,name=user"`
+	// `group` matches based on user group name.
 	// +optional
 	Group *GroupSubject `json:"group,omitempty" protobuf:"bytes,3,opt,name=group"`
+	// `serviceAccount` matches ServiceAccounts.
 	// +optional
 	ServiceAccount *ServiceAccountSubject `json:"serviceAccount,omitempty" protobuf:"bytes,4,opt,name=serviceAccount"`
 }

staging/src/k8s.io/api/flowcontrol/v1beta1/types_swagger_doc_generated.go

@@ -238,8 +238,11 @@ func (ServiceAccountSubject) SwaggerDoc() map[string]string {
 }
 
 var map_Subject = map[string]string{
-	"":     "Subject matches the originator of a request, as identified by the request authentication system. There are three ways of matching an originator; by user, group, or service account.",
-	"kind": "Required",
+	"":               "Subject matches the originator of a request, as identified by the request authentication system. There are three ways of matching an originator; by user, group, or service account.",
+	"kind":           "`kind` indicates which one of the other fields is non-empty. Required",
+	"user":           "`user` matches based on username.",
+	"group":          "`group` matches based on user group name.",
+	"serviceAccount": "`serviceAccount` matches ServiceAccounts.",
 }
 
 func (Subject) SwaggerDoc() map[string]string {