api/v3/clairpb: document and regenerate protos

api/v3/clairpb/clair.pb.gw.go

@@ -28,21 +28,6 @@ var _ status.Status
 var _ = runtime.String
 var _ = utilities.NewDoubleArray
 
-func request_AncestryService_PostAncestry_0(ctx context.Context, marshaler runtime.Marshaler, client AncestryServiceClient, req *http.Request, pathParams map[string]string) (proto.Message, runtime.ServerMetadata, error) {
-	var protoReq PostAncestryRequest
-	var metadata runtime.ServerMetadata
-
-	if req.ContentLength > 0 {
-		if err := marshaler.NewDecoder(req.Body).Decode(&protoReq); err != nil {
-			return nil, metadata, status.Errorf(codes.InvalidArgument, "%v", err)
-		}
-	}
-
-	msg, err := client.PostAncestry(ctx, &protoReq, grpc.Header(&metadata.HeaderMD), grpc.Trailer(&metadata.TrailerMD))
-	return msg, metadata, err
-
-}
-
 var (
 	filter_AncestryService_GetAncestry_0 = &utilities.DoubleArray{Encoding: map[string]int{"ancestry_name": 0}, Base: []int{1, 1, 0}, Check: []int{0, 1, 2}}
 )
@@ -78,6 +63,21 @@ func request_AncestryService_GetAncestry_0(ctx context.Context, marshaler runtim
 
 }
 
+func request_AncestryService_PostAncestry_0(ctx context.Context, marshaler runtime.Marshaler, client AncestryServiceClient, req *http.Request, pathParams map[string]string) (proto.Message, runtime.ServerMetadata, error) {
+	var protoReq PostAncestryRequest
+	var metadata runtime.ServerMetadata
+
+	if req.ContentLength > 0 {
+		if err := marshaler.NewDecoder(req.Body).Decode(&protoReq); err != nil {
+			return nil, metadata, status.Errorf(codes.InvalidArgument, "%v", err)
+		}
+	}
+
+	msg, err := client.PostAncestry(ctx, &protoReq, grpc.Header(&metadata.HeaderMD), grpc.Trailer(&metadata.TrailerMD))
+	return msg, metadata, err
+
+}
+
 var (
 	filter_NotificationService_GetNotification_0 = &utilities.DoubleArray{Encoding: map[string]int{"name": 0}, Base: []int{1, 1, 0}, Check: []int{0, 1, 2}}
 )
@@ -178,35 +178,6 @@ func RegisterAncestryServiceHandler(ctx context.Context, mux *runtime.ServeMux,
 // "AncestryServiceClient" to call the correct interceptors.
 func RegisterAncestryServiceHandlerClient(ctx context.Context, mux *runtime.ServeMux, client AncestryServiceClient) error {
 
-	mux.Handle("POST", pattern_AncestryService_PostAncestry_0, func(w http.ResponseWriter, req *http.Request, pathParams map[string]string) {
-		ctx, cancel := context.WithCancel(req.Context())
-		defer cancel()
-		if cn, ok := w.(http.CloseNotifier); ok {
-			go func(done <-chan struct{}, closed <-chan bool) {
-				select {
-				case <-done:
-				case <-closed:
-					cancel()
-				}
-			}(ctx.Done(), cn.CloseNotify())
-		}
-		inboundMarshaler, outboundMarshaler := runtime.MarshalerForRequest(mux, req)
-		rctx, err := runtime.AnnotateContext(ctx, mux, req)
-		if err != nil {
-			runtime.HTTPError(ctx, mux, outboundMarshaler, w, req, err)
-			return
-		}
-		resp, md, err := request_AncestryService_PostAncestry_0(rctx, inboundMarshaler, client, req, pathParams)
-		ctx = runtime.NewServerMetadataContext(ctx, md)
-		if err != nil {
-			runtime.HTTPError(ctx, mux, outboundMarshaler, w, req, err)
-			return
-		}
-
-		forward_AncestryService_PostAncestry_0(ctx, mux, outboundMarshaler, w, req, resp, mux.GetForwardResponseOptions()...)
-
-	})
-
 	mux.Handle("GET", pattern_AncestryService_GetAncestry_0, func(w http.ResponseWriter, req *http.Request, pathParams map[string]string) {
 		ctx, cancel := context.WithCancel(req.Context())
 		defer cancel()
@@ -236,19 +207,48 @@ func RegisterAncestryServiceHandlerClient(ctx context.Context, mux *runtime.Serv
 
 	})
 
+	mux.Handle("POST", pattern_AncestryService_PostAncestry_0, func(w http.ResponseWriter, req *http.Request, pathParams map[string]string) {
+		ctx, cancel := context.WithCancel(req.Context())
+		defer cancel()
+		if cn, ok := w.(http.CloseNotifier); ok {
+			go func(done <-chan struct{}, closed <-chan bool) {
+				select {
+				case <-done:
+				case <-closed:
+					cancel()
+				}
+			}(ctx.Done(), cn.CloseNotify())
+		}
+		inboundMarshaler, outboundMarshaler := runtime.MarshalerForRequest(mux, req)
+		rctx, err := runtime.AnnotateContext(ctx, mux, req)
+		if err != nil {
+			runtime.HTTPError(ctx, mux, outboundMarshaler, w, req, err)
+			return
+		}
+		resp, md, err := request_AncestryService_PostAncestry_0(rctx, inboundMarshaler, client, req, pathParams)
+		ctx = runtime.NewServerMetadataContext(ctx, md)
+		if err != nil {
+			runtime.HTTPError(ctx, mux, outboundMarshaler, w, req, err)
+			return
+		}
+
+		forward_AncestryService_PostAncestry_0(ctx, mux, outboundMarshaler, w, req, resp, mux.GetForwardResponseOptions()...)
+
+	})
+
 	return nil
 }
 
 var (
-	pattern_AncestryService_PostAncestry_0 = runtime.MustPattern(runtime.NewPattern(1, []int{2, 0}, []string{"ancestry"}, ""))
-
 	pattern_AncestryService_GetAncestry_0 = runtime.MustPattern(runtime.NewPattern(1, []int{2, 0, 1, 0, 4, 1, 5, 1}, []string{"ancestry", "ancestry_name"}, ""))
+
+	pattern_AncestryService_PostAncestry_0 = runtime.MustPattern(runtime.NewPattern(1, []int{2, 0}, []string{"ancestry"}, ""))
 )
 
 var (
-	forward_AncestryService_PostAncestry_0 = runtime.ForwardResponseMessage
-
 	forward_AncestryService_GetAncestry_0 = runtime.ForwardResponseMessage
+
+	forward_AncestryService_PostAncestry_0 = runtime.ForwardResponseMessage
 )
 
 // RegisterNotificationServiceHandlerFromEndpoint is same as RegisterNotificationServiceHandler but

api/v3/clairpb/clair.proto

@@ -1,4 +1,4 @@
-// Copyright 2017 clair authors
+// Copyright 2018 clair authors
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -16,150 +16,239 @@ syntax = "proto3";
 option go_package = "clairpb";
 
 package clairpb;
+
 import "google/api/annotations.proto";
 import "google/protobuf/empty.proto";
 import "google/protobuf/timestamp.proto";
 
 message Vulnerability {
+  // The name of the vulnerability.
   string name = 1;
+
+  // The name of the namespace in which the vulnerability was detected.
   string namespace_name = 2;
+
+  // A description of the vulnerability according to the source for the namespace.
   string description = 3;
+
+  // A link to the vulnerability according to the source for the namespace.
   string link = 4;
+
+  // How dangerous the vulnerability is.
   string severity = 5;
+
+  // Namespace agnostic metadata about the vulnerability.
   string metadata = 6;
-	// fixed_by exists when vulnerability is under feature.
+
+  // The feature that fixes this vulnerability.
+  // This field only exists when a vulnerability is a part of a Feature.
   string fixed_by = 7;
-	// affected_versions exists when vulnerability is under notification.
+
+  // The Features that are affected by the vulnerability.
+  // This field only exists when a vulnerability is a part of a Notification.
   repeated Feature affected_versions = 8;
 }
 
-message ClairStatus {
-	// listers and detectors are processors implemented in this Clair and used to
-	// scan ancestries
-	repeated string listers = 1;
-	repeated string detectors = 2;
-	google.protobuf.Timestamp last_update_time = 3;
-}
-
 message Feature {
+  // The name of the feature.
   string name = 1;
+
+  // The name of the namespace in which the feature is detected.
   string namespace_name = 2;
+
+  // The specific version of this feature.
   string version = 3;
 
-	// version_format is the format used by installer package manager to store
+  // The format used to parse version numbers for the feature.
-	// package versions.
   string version_format = 4;
+
+  // The list of vulnerabilities that affect the feature.
   repeated Vulnerability vulnerabilities = 5;
 }
 
-message Ancestry {
-	string name = 1;
-	repeated Feature features = 2;
-	repeated Layer layers = 3;
-
-	// scanned_listers and scanned_detectors are used to scan this ancestry, it
-	// may be different from listers and detectors in ClairStatus since the
-	// ancestry could be scanned by previous version of Clair.
-	repeated string scanned_listers = 4;
-	repeated string scanned_detectors = 5;
-}
-
 message Layer { 
+  // The sha256 tarsum for the layer.
   string hash = 1;
 }
 
-message Notification {
-	string name = 1;
-	string created = 2;
-	string notified = 3;
-	string deleted = 4;	
-	PagedVulnerableAncestries old = 5;
-	PagedVulnerableAncestries new = 6;
-}
-
-message IndexedAncestryName {
-	// index is unique to name in all streams simultaneously streamed, increasing
-	// and larger than all indexes in previous page in same stream.
-	int32 index = 1;
-	string name = 2;
-}
-
-message PagedVulnerableAncestries {
-	string current_page = 1;
-	// if next_page is empty, it signals the end of all pages.
-	string next_page = 2;
-	int32 limit = 3;	
-	Vulnerability vulnerability = 4;
-	repeated IndexedAncestryName ancestries = 5;
-}
-
-message PostAncestryRequest {
-	message PostLayer {
-		string hash = 1;
-		string path = 2;
-		map<string, string> headers = 3;
-	}
-	string ancestry_name = 1;
-	string format = 2;
-	repeated PostLayer layers = 3;
-}
-
-message PostAncestryResponse {
-	ClairStatus status = 1; 
-}
-
-message GetAncestryRequest {
-	string ancestry_name = 1;
-	bool with_vulnerabilities = 2;
-	bool with_features = 3;
-}
-
-message GetAncestryResponse {
-	Ancestry ancestry = 1;
-	ClairStatus status = 2; 
-}
-
-message GetNotificationRequest {
-	// if the vulnerability_page is empty, it implies the first page.
-	string old_vulnerability_page = 1;
-	string new_vulnerability_page = 2;
-	int32 limit = 3;
-	string name = 4;
-}
-
-message GetNotificationResponse {
-	Notification notification = 1;
-}
-
-message MarkNotificationAsReadRequest {
-	string name = 1;
-}
-
 service AncestryService {
+  // The RPC used to read the results of scanning for a particular ancestry.
+  rpc GetAncestry(GetAncestryRequest) returns (GetAncestryResponse) {
+    option (google.api.http) = {
+      get: "/ancestry/{ancestry_name}"
+    };
+  }
+
+  // The RPC used to create a new scan of an ancestry.
   rpc PostAncestry(PostAncestryRequest) returns (PostAncestryResponse) {
     option (google.api.http) = {
       post: "/ancestry"
       body: "*"
     };
   }
-
-	rpc GetAncestry(GetAncestryRequest) returns (GetAncestryResponse) {
-		option (google.api.http) = {
-			get: "/ancestry/{ancestry_name}"
-		};
 }
+
+message ClairStatus {
+  // The configured list of feature listers used to scan an ancestry.
+  repeated string listers = 1;
+
+  // The configured list of namespace detectors used to scan an ancestry.
+  repeated string detectors = 2;
+
+  // The time at which the updater last ran.
+  google.protobuf.Timestamp last_update_time = 3;
+}
+
+message GetAncestryRequest {
+  // The name of the desired ancestry.
+  string ancestry_name = 1;
+
+  // Whether to include vulnerabilities or not in the response.
+  bool with_vulnerabilities = 2;
+
+  // Whether to include features or not in the response.
+  bool with_features = 3;
+}
+
+message GetAncestryResponse {
+  message Ancestry {
+    // The name of the desired ancestry.
+    string name = 1;
+
+    // The list of features present in the ancestry.
+    // This will only be provided if requested.
+    repeated Feature features = 2;
+
+    // The layers present in the ancestry.
+    repeated Layer layers = 3;
+
+    // The configured list of feature listers used to scan this ancestry.
+    repeated string scanned_listers = 4;
+
+    // The configured list of namespace detectors used to scan an ancestry.
+    repeated string scanned_detectors = 5;
+  }
+
+  // The ancestry requested.
+  Ancestry ancestry = 1;
+
+  // The status of Clair at the time of the request.
+  ClairStatus status = 2; 
+}
+
+message PostAncestryRequest {
+  message PostLayer {
+    // The hash of the layer.
+    string hash = 1;
+
+    // The location of the layer (URL or filepath).
+    string path = 2;
+
+   // Any HTTP Headers that need to be used if requesting a layer over HTTP(S).
+   map<string, string> headers = 3;
+ }
+
+  // The name of the ancestry being scanned.
+  // If scanning OCI images, this should be the hash of the manifest.
+  string ancestry_name = 1;
+
+  // The format of the image being uploaded.
+  string format = 2;
+
+  // The layers to be scanned for this particular ancestry.
+  repeated PostLayer layers = 3;
+}
+
+message PostAncestryResponse {
+  // The status of Clair at the time of the request.
+  ClairStatus status = 1; 
 }
 
 service NotificationService {
+  // The RPC used to get a particularly Notification.
   rpc GetNotification(GetNotificationRequest) returns (GetNotificationResponse) {
     option (google.api.http) = {
       get: "/notifications/{name}"
     };
   }
 
+  // The RPC used to mark a Notification as read after it has been processed.
   rpc MarkNotificationAsRead(MarkNotificationAsReadRequest) returns (google.protobuf.Empty) {
     option (google.api.http) = {
       delete: "/notifications/{name}"
     };
   }
 }
+
+message GetNotificationRequest {
+  // The current page of previous vulnerabilities for the ancestry.
+  // This will be empty when it is the first page.
+  string old_vulnerability_page = 1;
+
+  // The current page of vulnerabilities for the ancestry.
+  // This will be empty when it is the first page.
+  string new_vulnerability_page = 2;
+
+  // The requested maximum number of results per page.
+  int32 limit = 3;
+
+  // The name of the notification being requested.
+  string name = 4;
+}
+
+message GetNotificationResponse {
+  message Notification {
+    // The name of the requested notification.
+    string name = 1;
+
+    // The time at which the notification was created.
+    string created = 2;
+
+    // The time at which the notification was last sent out.
+    string notified = 3;
+
+    // The time at which a notification has been deleted.
+    string deleted = 4; 
+
+    // The previous vulnerability and a paginated view of the ancestries it affects.
+    PagedVulnerableAncestries old = 5;
+
+    // The newly updated vulnerability and a paginated view of the ancestries it affects.
+    PagedVulnerableAncestries new = 6;
+  }
+
+  // The notification as requested.
+  Notification notification = 1;
+}
+
+message PagedVulnerableAncestries {
+  message IndexedAncestryName {
+    // The index is an ever increasing number associated with the particular ancestry.
+    // This is useful if you're processing notifications, and need to keep track of the progress of paginating the results.
+    int32 index = 1;
+
+    // The name of the ancestry.
+    string name = 2;
+  }
+
+  // The identifier for the current page.
+  string current_page = 1;
+
+  // The token used to request the next page.
+  // This will be empty when there are no more pages.
+  string next_page = 2;
+
+  // The requested maximum number of results per page.
+  int32 limit = 3;  
+
+  // The vulnerability that affects a given set of ancestries.
+  Vulnerability vulnerability = 4;
+
+  // The ancestries affected by a vulnerability.
+  repeated IndexedAncestryName ancestries = 5;
+}
+
+message MarkNotificationAsReadRequest {
+  // The name of the Notification that has been processed.
+  string name = 1;
+}

api/v3/clairpb/clair.swagger.json

@@ -17,6 +17,7 @@
   "paths": {
     "/ancestry": {
       "post": {
+        "summary": "The RPC used to create a new scan of an ancestry.",
         "operationId": "PostAncestry",
         "responses": {
           "200": {
@@ -43,6 +44,7 @@
     },
     "/ancestry/{ancestry_name}": {
       "get": {
+        "summary": "The RPC used to read the results of scanning for a particular ancestry.",
         "operationId": "GetAncestry",
         "responses": {
           "200": {
@@ -61,6 +63,7 @@
           },
           {
             "name": "with_vulnerabilities",
+            "description": "Whether to include vulnerabilities or not in the response.",
             "in": "query",
             "required": false,
             "type": "boolean",
@@ -68,6 +71,7 @@
           },
           {
             "name": "with_features",
+            "description": "Whether to include features or not in the response.",
             "in": "query",
             "required": false,
             "type": "boolean",
@@ -81,6 +85,7 @@
     },
     "/notifications/{name}": {
       "get": {
+        "summary": "The RPC used to get a particularly Notification.",
         "operationId": "GetNotification",
         "responses": {
           "200": {
@@ -99,19 +104,21 @@
           },
           {
             "name": "old_vulnerability_page",
-            "description": "if the vulnerability_page is empty, it implies the first page.",
+            "description": "The current page of previous vulnerabilities for the ancestry.\nThis will be empty when it is the first page.",
             "in": "query",
             "required": false,
             "type": "string"
           },
           {
             "name": "new_vulnerability_page",
+            "description": "The current page of vulnerabilities for the ancestry.\nThis will be empty when it is the first page.",
             "in": "query",
             "required": false,
             "type": "string"
           },
           {
             "name": "limit",
+            "description": "The requested maximum number of results per page.",
             "in": "query",
             "required": false,
             "type": "integer",
@@ -123,6 +130,7 @@
         ]
       },
       "delete": {
+        "summary": "The RPC used to mark a Notification as read after it has been processed.",
         "operationId": "MarkNotificationAsRead",
         "responses": {
           "200": {
@@ -147,54 +155,104 @@
     }
   },
   "definitions": {
-    "PostAncestryRequestPostLayer": {
+    "GetAncestryResponseAncestry": {
-      "type": "object",
-      "properties": {
-        "hash": {
-          "type": "string"
-        },
-        "path": {
-          "type": "string"
-        },
-        "headers": {
-          "type": "object",
-          "additionalProperties": {
-            "type": "string"
-          }
-        }
-      }
-    },
-    "clairpbAncestry": {
       "type": "object",
       "properties": {
         "name": {
-          "type": "string"
+          "type": "string",
+          "description": "The name of the desired ancestry."
         },
         "features": {
           "type": "array",
           "items": {
             "$ref": "#/definitions/clairpbFeature"
-          }
+          },
+          "description": "The list of features present in the ancestry.\nThis will only be provided if requested."
         },
         "layers": {
           "type": "array",
           "items": {
             "$ref": "#/definitions/clairpbLayer"
-          }
+          },
+          "description": "The layers present in the ancestry."
         },
         "scanned_listers": {
           "type": "array",
           "items": {
             "type": "string"
           },
-          "description": "scanned_listers and scanned_detectors are used to scan this ancestry, it\nmay be different from listers and detectors in ClairStatus since the\nancestry could be scanned by previous version of Clair."
+          "description": "The configured list of feature listers used to scan this ancestry."
         },
         "scanned_detectors": {
           "type": "array",
           "items": {
             "type": "string"
+          },
+          "description": "The configured list of namespace detectors used to scan an ancestry."
         }
       }
+    },
+    "GetNotificationResponseNotification": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "The name of the requested notification."
+        },
+        "created": {
+          "type": "string",
+          "description": "The time at which the notification was created."
+        },
+        "notified": {
+          "type": "string",
+          "description": "The time at which the notification was last sent out."
+        },
+        "deleted": {
+          "type": "string",
+          "description": "The time at which a notification has been deleted."
+        },
+        "old": {
+          "$ref": "#/definitions/clairpbPagedVulnerableAncestries",
+          "description": "The previous vulnerability and a paginated view of the ancestries it affects."
+        },
+        "new": {
+          "$ref": "#/definitions/clairpbPagedVulnerableAncestries",
+          "description": "The newly updated vulnerability and a paginated view of the ancestries it affects."
+        }
+      }
+    },
+    "PagedVulnerableAncestriesIndexedAncestryName": {
+      "type": "object",
+      "properties": {
+        "index": {
+          "type": "integer",
+          "format": "int32",
+          "description": "The index is an ever increasing number associated with the particular ancestry.\nThis is useful if you're processing notifications, and need to keep track of the progress of paginating the results."
+        },
+        "name": {
+          "type": "string",
+          "description": "The name of the ancestry."
+        }
+      }
+    },
+    "PostAncestryRequestPostLayer": {
+      "type": "object",
+      "properties": {
+        "hash": {
+          "type": "string",
+          "description": "The hash of the layer."
+        },
+        "path": {
+          "type": "string",
+          "description": "The location of the layer (URL or filepath)."
+        },
+        "headers": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          },
+          "description": "Any HTTP Headers that need to be used if requesting a layer over HTTP(S)."
+        }
       }
     },
     "clairpbClairStatus": {
@@ -205,17 +263,19 @@
           "items": {
             "type": "string"
           },
-          "title": "listers and detectors are processors implemented in this Clair and used to\nscan ancestries"
+          "description": "The configured list of feature listers used to scan an ancestry."
         },
         "detectors": {
           "type": "array",
           "items": {
             "type": "string"
-          }
+          },
+          "description": "The configured list of namespace detectors used to scan an ancestry."
         },
         "last_update_time": {
           "type": "string",
-          "format": "date-time"
+          "format": "date-time",
+          "description": "The time at which the updater last ran."
         }
       }
     },
@@ -223,23 +283,27 @@
       "type": "object",
       "properties": {
         "name": {
-          "type": "string"
+          "type": "string",
+          "description": "The name of the feature."
         },
         "namespace_name": {
-          "type": "string"
+          "type": "string",
+          "description": "The name of the namespace in which the feature is detected."
         },
         "version": {
-          "type": "string"
+          "type": "string",
+          "description": "The specific version of this feature."
         },
         "version_format": {
           "type": "string",
-          "description": "version_format is the format used by installer package manager to store\npackage versions."
+          "description": "The format used to parse version numbers for the feature."
         },
         "vulnerabilities": {
           "type": "array",
           "items": {
             "$ref": "#/definitions/clairpbVulnerability"
-          }
+          },
+          "description": "The list of vulnerabilities that affect the feature."
         }
       }
     },
@@ -247,10 +311,12 @@
       "type": "object",
       "properties": {
         "ancestry": {
-          "$ref": "#/definitions/clairpbAncestry"
+          "$ref": "#/definitions/GetAncestryResponseAncestry",
+          "description": "The ancestry requested."
         },
         "status": {
-          "$ref": "#/definitions/clairpbClairStatus"
+          "$ref": "#/definitions/clairpbClairStatus",
+          "description": "The status of Clair at the time of the request."
         }
       }
     },
@@ -258,20 +324,8 @@
       "type": "object",
       "properties": {
         "notification": {
-          "$ref": "#/definitions/clairpbNotification"
+          "$ref": "#/definitions/GetNotificationResponseNotification",
-        }
+          "description": "The notification as requested."
-      }
-    },
-    "clairpbIndexedAncestryName": {
-      "type": "object",
-      "properties": {
-        "index": {
-          "type": "integer",
-          "format": "int32",
-          "description": "index is unique to name in all streams simultaneously streamed, increasing\nand larger than all indexes in previous page in same stream."
-        },
-        "name": {
-          "type": "string"
         }
       }
     },
@@ -279,30 +333,8 @@
       "type": "object",
       "properties": {
         "hash": {
-          "type": "string"
+          "type": "string",
-        }
+          "description": "The sha256 tarsum for the layer."
-      }
-    },
-    "clairpbNotification": {
-      "type": "object",
-      "properties": {
-        "name": {
-          "type": "string"
-        },
-        "created": {
-          "type": "string"
-        },
-        "notified": {
-          "type": "string"
-        },
-        "deleted": {
-          "type": "string"
-        },
-        "old": {
-          "$ref": "#/definitions/clairpbPagedVulnerableAncestries"
-        },
-        "new": {
-          "$ref": "#/definitions/clairpbPagedVulnerableAncestries"
         }
       }
     },
@@ -310,24 +342,28 @@
       "type": "object",
       "properties": {
         "current_page": {
-          "type": "string"
+          "type": "string",
+          "description": "The identifier for the current page."
         },
         "next_page": {
           "type": "string",
-          "description": "if next_page is empty, it signals the end of all pages."
+          "description": "The token used to request the next page.\nThis will be empty when there are no more pages."
         },
         "limit": {
           "type": "integer",
-          "format": "int32"
+          "format": "int32",
+          "description": "The requested maximum number of results per page."
         },
         "vulnerability": {
-          "$ref": "#/definitions/clairpbVulnerability"
+          "$ref": "#/definitions/clairpbVulnerability",
+          "description": "The vulnerability that affects a given set of ancestries."
         },
         "ancestries": {
           "type": "array",
           "items": {
-            "$ref": "#/definitions/clairpbIndexedAncestryName"
+            "$ref": "#/definitions/PagedVulnerableAncestriesIndexedAncestryName"
-          }
+          },
+          "description": "The ancestries affected by a vulnerability."
         }
       }
     },
@@ -335,16 +371,19 @@
       "type": "object",
       "properties": {
         "ancestry_name": {
-          "type": "string"
+          "type": "string",
+          "description": "The name of the ancestry being scanned.\nIf scanning OCI images, this should be the hash of the manifest."
         },
         "format": {
-          "type": "string"
+          "type": "string",
+          "description": "The format of the image being uploaded."
         },
         "layers": {
           "type": "array",
           "items": {
             "$ref": "#/definitions/PostAncestryRequestPostLayer"
-          }
+          },
+          "description": "The layers to be scanned for this particular ancestry."
         }
       }
     },
@@ -352,7 +391,8 @@
       "type": "object",
       "properties": {
         "status": {
-          "$ref": "#/definitions/clairpbClairStatus"
+          "$ref": "#/definitions/clairpbClairStatus",
+          "description": "The status of Clair at the time of the request."
         }
       }
     },
@@ -360,33 +400,39 @@
       "type": "object",
       "properties": {
         "name": {
-          "type": "string"
+          "type": "string",
+          "description": "The name of the vulnerability."
         },
         "namespace_name": {
-          "type": "string"
+          "type": "string",
+          "description": "The name of the namespace in which the vulnerability was detected."
         },
         "description": {
-          "type": "string"
+          "type": "string",
+          "description": "A description of the vulnerability according to the source for the namespace."
         },
         "link": {
-          "type": "string"
+          "type": "string",
+          "description": "A link to the vulnerability according to the source for the namespace."
         },
         "severity": {
-          "type": "string"
+          "type": "string",
+          "description": "How dangerous the vulnerability is."
         },
         "metadata": {
-          "type": "string"
+          "type": "string",
+          "description": "Namespace agnostic metadata about the vulnerability."
         },
         "fixed_by": {
           "type": "string",
-          "description": "fixed_by exists when vulnerability is under feature."
+          "description": "The feature that fixes this vulnerability.\nThis field only exists when a vulnerability is a part of a Feature."
         },
         "affected_versions": {
           "type": "array",
           "items": {
             "$ref": "#/definitions/clairpbFeature"
           },
-          "description": "affected_versions exists when vulnerability is under notification."
+          "description": "The Features that are affected by the vulnerability.\nThis field only exists when a vulnerability is a part of a Notification."
         }
       }
     },

api/v3/clairpb/convert.go

@@ -48,7 +48,7 @@ func PagedVulnerableAncestriesFromDatabaseModel(dbVuln *database.PagedVulnerable
 	}
 
 	for index, ancestryName := range dbVuln.Affected {
-		indexedAncestry := IndexedAncestryName{
+		indexedAncestry := PagedVulnerableAncestries_IndexedAncestryName{
 			Name:  ancestryName,
 			Index: int32(index),
 		}
@@ -60,9 +60,9 @@ func PagedVulnerableAncestriesFromDatabaseModel(dbVuln *database.PagedVulnerable
 
 // NotificationFromDatabaseModel converts database notification, old and new
 // vulnerabilities' paged vulnerable ancestries to be api notification.
-func NotificationFromDatabaseModel(dbNotification database.VulnerabilityNotificationWithVulnerable) (*Notification, error) {
+func NotificationFromDatabaseModel(dbNotification database.VulnerabilityNotificationWithVulnerable) (*GetNotificationResponse_Notification, error) {
 	var (
-		noti Notification
+		noti GetNotificationResponse_Notification
 		err  error
 	)
 
@@ -123,8 +123,8 @@ func VulnerabilityWithFixedInFromDatabaseModel(dbVuln database.VulnerabilityWith
 }
 
 // AncestryFromDatabaseModel converts database ancestry to api ancestry.
-func AncestryFromDatabaseModel(dbAncestry database.Ancestry) *Ancestry {
+func AncestryFromDatabaseModel(dbAncestry database.Ancestry) *GetAncestryResponse_Ancestry {
-	ancestry := &Ancestry{
+	ancestry := &GetAncestryResponse_Ancestry{
 		Name: dbAncestry.Name,
 	}
 	for _, layer := range dbAncestry.Layers {