fixes to swagger file

Author: miparnisari

authzed/api/v1/experimental_service.proto

@@ -7,6 +7,7 @@ import "buf/validate/validate.proto";
 import "google/api/annotations.proto";
 import "google/protobuf/struct.proto";
 import "google/rpc/status.proto";
+import "protoc-gen-openapiv2/options/annotations.proto";
 import "validate/validate.proto";
 
 option go_package = "github.com/authzed/authzed-go/proto/authzed/api/v1";
@@ -16,39 +17,39 @@ option java_package = "com.authzed.api.v1";
 // ExperimentalService exposes a number of APIs that are currently being
 // prototyped and tested for future inclusion in the stable API.
 service ExperimentalService {
-  // BulkImportRelationships is a faster path to writing a large number of
-  // relationships at once. It is both batched and streaming. For maximum
-  // performance, the caller should attempt to write relationships in as close
-  // to relationship sort order as possible: (resource.object_type,
-  // resource.object_id, relation, subject.object.object_type,
-  // subject.object.object_id, subject.optional_relation)
-  //
-  // EXPERIMENTAL
-  // https://github.com/authzed/spicedb/issues/1303
+  // DEPRECATED: Promoted to ImportBulkRelationships in the stable API.
   rpc BulkImportRelationships(stream BulkImportRelationshipsRequest) returns (BulkImportRelationshipsResponse) {
     option (google.api.http) = {
       post: "/v1/experimental/relationships/bulkimport"
       body: "*"
     };
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: ["Deprecated"]
+    };
+    option deprecated = true;
   }
 
-  // BulkExportRelationships is the fastest path available to exporting
-  // relationships from the server. It is resumable, and will return results
-  // in an order determined by the server.
+  // DEPRECATED: Promoted to ExportBulkRelationships in the stable API.
   rpc BulkExportRelationships(BulkExportRelationshipsRequest) returns (stream BulkExportRelationshipsResponse) {
     option (google.api.http) = {
       post: "/v1/experimental/relationships/bulkexport"
       body: "*"
     };
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: ["Deprecated"]
+    };
+    option deprecated = true;
   }
 
-  // NOTE: BulkCheckPermission has been promoted to the stable API as "CheckBulkPermission" and the
-  // API will be removed from experimental in a future release.
+  // DEPRECATED: Promoted to CheckBulkPermission in the stable API.
   rpc BulkCheckPermission(BulkCheckPermissionRequest) returns (BulkCheckPermissionResponse) {
     option (google.api.http) = {
       post: "/v1/experimental/permissions/bulkcheckpermission"
       body: "*"
     };
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: ["Deprecated"]
+    };
     option deprecated = true;
   }
 
@@ -58,6 +59,9 @@ service ExperimentalService {
       post: "/v1/experimental/reflectschema"
       body: "*"
     };
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: ["Deprecated"]
+    };
     option deprecated = true;
   }
 
@@ -67,6 +71,9 @@ service ExperimentalService {
       post: "/v1/experimental/permissions/computable"
       body: "*"
     };
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: ["Deprecated"]
+    };
     option deprecated = true;
   }
 
@@ -76,6 +83,9 @@ service ExperimentalService {
       post: "/v1/experimental/permissions/dependent"
       body: "*"
     };
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: ["Deprecated"]
+    };
     option deprecated = true;
   }
 
@@ -85,6 +95,9 @@ service ExperimentalService {
       post: "/v1/experimental/diffschema"
       body: "*"
     };
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: ["Deprecated"]
+    };
     option deprecated = true;
   }
 
@@ -95,6 +108,9 @@ service ExperimentalService {
       post: "/v1/experimental/registerrelationshipcounter"
       body: "*"
     };
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: ["Experimental"]
+    };
   }
 
   // EXPERIMENTAL: CountRelationships returns the count of relationships for *pre-registered* filter.
@@ -103,6 +119,9 @@ service ExperimentalService {
       post: "/v1/experimental/countrelationships"
       body: "*"
     };
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: ["Experimental"]
+    };
   }
 
   // EXPERIMENTAL: UnregisterRelationshipCounter unregisters an existing filter for counting relationships.
@@ -111,6 +130,9 @@ service ExperimentalService {
       post: "/v1/experimental/unregisterrelationshipcounter"
       body: "*"
     };
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: ["Experimental"]
+    };
   }
 }
 

authzed/api/v1/permission_service.proto

@@ -8,6 +8,7 @@ import "google/api/annotations.proto";
 import "google/protobuf/struct.proto";
 import "google/protobuf/timestamp.proto";
 import "google/rpc/status.proto";
+import "protoc-gen-openapiv2/options/annotations.proto";
 import "validate/validate.proto";
 
 option go_package = "github.com/authzed/authzed-go/proto/authzed/api/v1";
@@ -24,6 +25,9 @@ service PermissionsService {
       post: "/v1/relationships/read"
       body: "*"
     };
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: ["Permissions"]
+    };
   }
 
   // WriteRelationships atomically writes and/or deletes a set of specified
@@ -34,6 +38,9 @@ service PermissionsService {
       post: "/v1/relationships/write"
       body: "*"
     };
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: ["Permissions"]
+    };
   }
 
   // DeleteRelationships atomically bulk deletes all relationships matching the
@@ -45,6 +52,9 @@ service PermissionsService {
       post: "/v1/relationships/delete"
       body: "*"
     };
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: ["Permissions"]
+    };
   }
 
   // CheckPermission determines for a given resource whether a subject computes
@@ -54,6 +64,9 @@ service PermissionsService {
       post: "/v1/permissions/check"
       body: "*"
     };
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: ["Permissions"]
+    };
   }
 
   // CheckBulkPermissions evaluates the given list of permission checks
@@ -63,6 +76,9 @@ service PermissionsService {
       post: "/v1/permissions/checkbulk"
       body: "*"
     };
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: ["Permissions"]
+    };
   }
 
   // ExpandPermissionTree reveals the graph structure for a resource's
@@ -73,6 +89,9 @@ service PermissionsService {
       post: "/v1/permissions/expand"
       body: "*"
     };
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: ["Permissions"]
+    };
   }
 
   // LookupResources returns all the resources of a given type that a subject
@@ -82,6 +101,9 @@ service PermissionsService {
       post: "/v1/permissions/resources"
       body: "*"
     };
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: ["Permissions"]
+    };
   }
 
   // LookupSubjects returns all the subjects of a given type that
@@ -91,6 +113,9 @@ service PermissionsService {
       post: "/v1/permissions/subjects"
       body: "*"
     };
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: ["Permissions"]
+    };
   }
 
   // ImportBulkRelationships is a faster path to writing a large number of
@@ -105,6 +130,9 @@ service PermissionsService {
       post: "/v1/relationships/importbulk"
       body: "*"
     };
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: ["Permissions"]
+    };
   }
 
   // ExportBulkRelationships is the fastest path available to exporting
@@ -115,6 +143,9 @@ service PermissionsService {
       post: "/v1/relationships/exportbulk"
       body: "*"
     };
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: ["Permissions"]
+    };
   }
 }
 

authzed/api/v1/schema_service.proto

@@ -5,6 +5,7 @@ import "authzed/api/v1/core.proto";
 import "authzed/api/v1/permission_service.proto";
 import "buf/validate/validate.proto";
 import "google/api/annotations.proto";
+import "protoc-gen-openapiv2/options/annotations.proto";
 import "validate/validate.proto";
 
 option go_package = "github.com/authzed/authzed-go/proto/authzed/api/v1";
@@ -23,6 +24,9 @@ service SchemaService {
       post: "/v1/schema/read"
       body: "*"
     };
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: ["Schema"]
+    };
   }
 
   // Write overwrites the current Object Definitions for a Permissions System.
@@ -31,6 +35,9 @@ service SchemaService {
       post: "/v1/schema/write"
       body: "*"
     };
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: ["Schema"]
+    };
   }
 
   // ReflectSchema reflects the current schema stored in SpiceDB, returning a structural
@@ -40,6 +47,9 @@ service SchemaService {
       post: "/v1/schema/reflectschema"
       body: "*"
     };
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: ["Schema"]
+    };
   }
 
   // ComputablePermissions returns the set of permissions that compute based off a relation
@@ -51,6 +61,9 @@ service SchemaService {
       post: "/v1/schema/permissions/computable"
       body: "*"
     };
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: ["Schema"]
+    };
   }
 
   // DependentRelations returns the set of relations and permissions that used
@@ -61,6 +74,9 @@ service SchemaService {
       post: "/v1/schema/permissions/dependent"
       body: "*"
     };
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: ["Schema"]
+    };
   }
 
   // DiffSchema returns the difference between the specified schema and the current
@@ -70,6 +86,9 @@ service SchemaService {
       post: "/v1/schema/diffschema"
       body: "*"
     };
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: ["Schema"]
+    };
   }
 }
 

authzed/api/v1/watch_service.proto

@@ -6,18 +6,24 @@ import "authzed/api/v1/permission_service.proto";
 import "buf/validate/validate.proto";
 import "google/api/annotations.proto";
 import "google/protobuf/struct.proto";
+import "protoc-gen-openapiv2/options/annotations.proto";
 import "validate/validate.proto";
 
 option go_package = "github.com/authzed/authzed-go/proto/authzed/api/v1";
 option java_multiple_files = true;
 option java_package = "com.authzed.api.v1";
 
 service WatchService {
+  // Watch returns a stream of events that occurred in the datastore in ascending timestamp order.
+  // The events can be relationship updates, schema updates, or checkpoints.
   rpc Watch(WatchRequest) returns (stream WatchResponse) {
     option (google.api.http) = {
       post: "/v1/watch"
       body: "*"
     };
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: ["Watch"]
+    };
   }
 }
 

buf.gen.yaml

@@ -7,3 +7,4 @@ plugins:
     opt:
       - "openapi_naming_strategy=simple"
       - "allow_merge=true"
+      - "disable_service_tags=true"