docs: enhance the API protobuf documentation (#33)

Author: jon-whit

api/openapiv2/authorizer/accesscontroller/v1alpha1/check_service.swagger.json

@@ -18,7 +18,7 @@
   "paths": {
     "/authorizer/access-controller/v1alpha1/check": {
       "get": {
-        "summary": "Check performs an authorization check.",
+        "summary": "Check performs an access-control check by looking up if a specific subject\nis related to an object.",
         "operationId": "CheckService_Check",
         "responses": {
           "200": {
@@ -37,35 +37,35 @@
         "parameters": [
           {
             "name": "namespace",
-            "description": "The namespace to evaluate the check.\n\nNote: If you use the Expand API and the check\nevaluates a RelationTuple specifying a SubjectSet as\nsubject or due to a rewrite rule in a namespace config\nthis check request may involve other namespaces automatically.",
+            "description": "The namespace to evaluate the check within.",
             "in": "query",
             "required": false,
             "type": "string"
           },
           {
             "name": "object",
-            "description": "The related object in this check.",
+            "description": "The object to check.",
             "in": "query",
             "required": false,
             "type": "string"
           },
           {
             "name": "relation",
-            "description": "The relation between the Object and the Subject.",
+            "description": "The relation between the object and the subject.",
             "in": "query",
             "required": false,
             "type": "string"
           },
           {
             "name": "subject.id",
-            "description": "A concrete id of the subject.",
+            "description": "A concrete subject id string for the subject.",
             "in": "query",
             "required": false,
             "type": "string"
           },
           {
             "name": "subject.set.namespace",
-            "description": "The namespace of the object and relation\nreferenced in this subject set.",
+            "description": "The namespace of the object and relation referenced in this SubjectSet.",
             "in": "query",
             "required": false,
             "type": "string"
@@ -79,7 +79,14 @@
           },
           {
             "name": "subject.set.relation",
-            "description": "The relation to the object by the subjects.",
+            "description": "The relation between the object and the subject(s).",
+            "in": "query",
+            "required": false,
+            "type": "string"
+          },
+          {
+            "name": "snaptoken",
+            "description": "Optional. The snapshot token that encodes the evaluation timestamp that this request will be evaluated no earlier than.\n\nIf no snapshot token is provided the check request is evaluated against the most recently replicated version of the relation\ntuple storage. Leaving an empty snapshot token will reflect the latest changes, but it may incur a read penalty because the\nreads have to be directed toward the leaseholder of the replica that serves the data.\n\nWe call requests without a snapshot token a content-change check, because such requests require a round-trip read but return\nthe most recent writes and are thus good candidates for checking real-time content changes before an object is persisted.",
             "in": "query",
             "required": false,
             "type": "string"
@@ -127,7 +134,11 @@
       "properties": {
         "allowed": {
           "type": "boolean",
-          "description": "Whether the specified subject is\nrelated to the requested object.\n\nIt is false by default if no ACL matches."
+          "description": "A boolean indicating if the specified subject is related to the requested object.\n\nIt is false by default if no ACL matches."
+        },
+        "snaptoken": {
+          "type": "string",
+          "description": "A snapshot token encoding the snapshot evaluation timestamp that the request was evaluated at."
         }
       },
       "description": "The response for a CheckService.Check rpc."
@@ -137,32 +148,32 @@
       "properties": {
         "id": {
           "type": "string",
-          "description": "A concrete id of the subject."
+          "description": "A concrete subject id string for the subject."
         },
         "set": {
           "$ref": "#/definitions/v1alpha1SubjectSet",
-          "description": "A subject set that expands to more Subjects\n(used for inheritance)."
+          "description": "A SubjectSet that expands to more Subjects."
         }
       },
-      "description": "Subject is either a concrete subject id or\na subject set expanding to more Subjects."
+      "description": "Subject is either a concrete subject id string or\na SubjectSet expanding to more Subjects."
     },
     "v1alpha1SubjectSet": {
       "type": "object",
       "properties": {
         "namespace": {
           "type": "string",
-          "description": "The namespace of the object and relation\nreferenced in this subject set."
+          "description": "The namespace of the object and relation referenced in this SubjectSet."
         },
         "object": {
           "type": "string",
           "description": "The object selected by the subjects."
         },
         "relation": {
           "type": "string",
-          "description": "The relation to the object by the subjects."
+          "description": "The relation between the object and the subject(s)."
         }
       },
-      "description": "SubjectSet refers to all subjects which have\nthe same `relation` to an `object`.\nIt is also used for inheritance."
+      "description": "A SubjectSet refers to all subjects which have the same\nrelation to an object."
     }
   }
 }

api/openapiv2/authorizer/accesscontroller/v1alpha1/expand_service.swagger.json

@@ -52,7 +52,7 @@
       "properties": {
         "tree": {
           "$ref": "#/definitions/v1alpha1SubjectTree",
-          "description": "The tree the requested subject set expands to.\nThe requested subject set is the subject of the root.\n\nThis field can be nil in some circumstances."
+          "description": "The tree the requested SubjectSet expands to. The requested\nSubjectSet is the subject of the root.\n\nThis field can be nil in some circumstances."
         }
       },
       "description": "The response for an ExpandService.Expand rpc."
@@ -66,39 +66,39 @@
         "NODE_TYPE_LEAF"
       ],
       "default": "NODE_TYPE_UNSPECIFIED",
-      "description": " - NODE_TYPE_UNION: This node expands to a union of all children.\n - NODE_TYPE_INTERSECTION: This node expands to an intersection of the children.\n - NODE_TYPE_LEAF: This node is a leaf and contains no children.\nIts subject is a `SubjectID` unless `max_depth` was reached."
+      "description": "An enumeration defining types of nodes within a SubjectTree.\n\n - NODE_TYPE_UNION: A node type which expands to a union of all children.\n - NODE_TYPE_INTERSECTION: A node type which expands to an intersection of the children.\n - NODE_TYPE_LEAF: A node type which is a leaf and contains no children.\n\nIts Subject is a subject id string unless the maximum call depth was reached."
     },
     "v1alpha1Subject": {
       "type": "object",
       "properties": {
         "id": {
           "type": "string",
-          "description": "A concrete id of the subject."
+          "description": "A concrete subject id string for the subject."
         },
         "set": {
           "$ref": "#/definitions/v1alpha1SubjectSet",
-          "description": "A subject set that expands to more Subjects\n(used for inheritance)."
+          "description": "A SubjectSet that expands to more Subjects."
         }
       },
-      "description": "Subject is either a concrete subject id or\na subject set expanding to more Subjects."
+      "description": "Subject is either a concrete subject id string or\na SubjectSet expanding to more Subjects."
     },
     "v1alpha1SubjectSet": {
       "type": "object",
       "properties": {
         "namespace": {
           "type": "string",
-          "description": "The namespace of the object and relation\nreferenced in this subject set."
+          "description": "The namespace of the object and relation referenced in this SubjectSet."
         },
         "object": {
           "type": "string",
           "description": "The object selected by the subjects."
         },
         "relation": {
           "type": "string",
-          "description": "The relation to the object by the subjects."
+          "description": "The relation between the object and the subject(s)."
         }
       },
-      "description": "SubjectSet refers to all subjects which have\nthe same `relation` to an `object`.\nIt is also used for inheritance."
+      "description": "A SubjectSet refers to all subjects which have the same\nrelation to an object."
     },
     "v1alpha1SubjectTree": {
       "type": "object",

api/openapiv2/authorizer/accesscontroller/v1alpha1/namespace_service.swagger.json

@@ -37,6 +37,7 @@
         "parameters": [
           {
             "name": "namespace",
+            "description": "The namespace whose config should be read.",
             "in": "query",
             "required": false,
             "type": "string"
@@ -47,8 +48,8 @@
         ]
       },
       "put": {
-        "summary": "WriteConfig upserts a namespace configuration. If the namespace config already exists,\nthe existing one is overwritten.",
-        "description": "If the new namespace config removes an existing relation, there must not be any relation\ntuples that reference it. Otherwise a FAILED_PRECONDITION status is returned. To migrate\naway from a relation, please move all existing relation tuples referencing it over to the\nnew relation and then delete the old relation once all tuples have been migrated.",
+        "summary": "WriteConfig upserts a namespace configuration.",
+        "description": "If the namespace config already exists, the existing one is overwritten. If the new\nnamespace config removes an existing relation, there must not be any relation tuples\nthat reference it. Otherwise a FAILED_PRECONDITION status is returned.\n\nTo migrate away from a relation, please move all existing relation tuples referencing\nit over to the new relation and then delete the old relation once all tuples have been\nmigrated.",
         "operationId": "NamespaceConfigService_WriteConfig",
         "responses": {
           "200": {
@@ -82,7 +83,8 @@
   },
   "definitions": {
     "ChildThis": {
-      "type": "object"
+      "type": "object",
+      "description": "This references the defined relation directly."
     },
     "SetOperationChild": {
       "type": "object",
@@ -145,30 +147,36 @@
         "relation": {
           "type": "string"
         }
-      }
+      },
+      "description": "Computes the set of subjects that have the included relation within the\nsame namespace.\n\nThis is useful to follow relations between an object and subject within\nthe same namespace. If you want anyone with an 'editor' relation to also\nhave 'viewer' this would be a good fit."
     },
     "v1alpha1NamespaceConfig": {
       "type": "object",
       "properties": {
         "name": {
-          "type": "string"
+          "type": "string",
+          "description": "The name of the namespace."
         },
         "relations": {
           "type": "array",
           "items": {
             "$ref": "#/definitions/v1alpha1Relation"
-          }
+          },
+          "description": "The relations that this namespace defines."
         }
-      }
+      },
+      "description": "A namespace config defines the relations that exist between objects and subjects in\nin a namespace."
     },
     "v1alpha1ReadConfigResponse": {
       "type": "object",
       "properties": {
         "namespace": {
-          "type": "string"
+          "type": "string",
+          "description": "The namespace of the config."
         },
         "config": {
-          "$ref": "#/definitions/v1alpha1NamespaceConfig"
+          "$ref": "#/definitions/v1alpha1NamespaceConfig",
+          "description": "The namespace config for the given namespace."
         }
       },
       "description": "The response for a NamespaceConfigService.ReadConfig rpc."
@@ -177,23 +185,29 @@
       "type": "object",
       "properties": {
         "name": {
-          "type": "string"
+          "type": "string",
+          "description": "The name of the relation (e.g. viewer, editor, or member)."
         },
         "rewrite": {
-          "$ref": "#/definitions/v1alpha1Rewrite"
+          "$ref": "#/definitions/v1alpha1Rewrite",
+          "description": "The rewrite rule for this relation, or nil if it references itself."
         }
-      }
+      },
+      "description": "A Relation defines a type of relationship between an object and subject.\n\nRelations can have rewrite rules that specify how the relation is\ncomputed relative to other relations defined within the same namespace\nor across other namespaces."
     },
     "v1alpha1Rewrite": {
       "type": "object",
       "properties": {
         "union": {
-          "$ref": "#/definitions/v1alpha1SetOperation"
+          "$ref": "#/definitions/v1alpha1SetOperation",
+          "description": "Joins the children of the rewrite via set union."
         },
         "intersection": {
-          "$ref": "#/definitions/v1alpha1SetOperation"
+          "$ref": "#/definitions/v1alpha1SetOperation",
+          "description": "Joins the children of the rewrite via set intersection."
         }
-      }
+      },
+      "description": "Rewrites define sub-expressions that combine operations such as union or intersection. A rewrite\nsub-expression can be recursive and thus allows arbitrary logical expressions to be constructed."
     },
     "v1alpha1SetOperation": {
       "type": "object",
@@ -210,18 +224,22 @@
       "type": "object",
       "properties": {
         "tupleset": {
-          "$ref": "#/definitions/TupleToSubjectsetTupleset"
+          "$ref": "#/definitions/TupleToSubjectsetTupleset",
+          "description": "A tupleset defining the relation tuples that relate to the set of subjects that\nthis TupleToSubjectset applies to."
         },
         "computedSubjectset": {
-          "$ref": "#/definitions/v1alpha1ComputedSubjectset"
+          "$ref": "#/definitions/v1alpha1ComputedSubjectset",
+          "description": "The computed set of subjects that are looked up based on the expanded tupleset."
         }
-      }
+      },
+      "description": "Computes a tupleset from the input object, fetches relation tuples matching the\ntupleset, and computes the set of subjects from every fetched relation tuple.\n\nThis is useful to lookup relations in other namespaces or to create complex hierarchies\nbetween objects in multiple namespaces."
     },
     "v1alpha1WriteConfigRequest": {
       "type": "object",
       "properties": {
         "config": {
-          "$ref": "#/definitions/v1alpha1NamespaceConfig"
+          "$ref": "#/definitions/v1alpha1NamespaceConfig",
+          "description": "The namespace config to upsert."
         }
       },
       "description": "The request for a NamespaceConfigService.WriteConfig rpc."