Improve Canton openApi Docs generating directly from annotated protos

community/daml-lf/ledger-api-value-proto/src/main/protobuf/com/daml/ledger/api/v2/value.proto

@@ -10,6 +10,7 @@ package com.daml.ledger.api.v2;
 
 import "google/protobuf/empty.proto";
 
+option go_package = "github.com/digital-asset/canton/go/ledger/api/v2;ledgerapiv2";
 option csharp_namespace = "Com.Daml.Ledger.Api.V2";
 option java_outer_classname = "ValueOuterClass";
 option java_package = "com.daml.ledger.api.v2";

community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/admin/command_inspection_service.proto

@@ -10,6 +10,7 @@ import "com/daml/ledger/api/v2/completion.proto";
 import "com/daml/ledger/api/v2/value.proto";
 import "google/protobuf/timestamp.proto";
 
+option go_package = "github.com/digital-asset/canton/go/ledger/api/v2/admin;adminv2";
 option csharp_namespace = "Com.Daml.Ledger.Api.V2.Admin";
 option java_outer_classname = "CommandInspectionServiceOuterClass";
 option java_package = "com.daml.ledger.api.v2.admin";

community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/admin/identity_provider_config_service.proto

@@ -5,8 +5,10 @@ syntax = "proto3";
 
 package com.daml.ledger.api.v2.admin;
 
+import "google/api/annotations.proto";
 import "google/protobuf/field_mask.proto";
 
+option go_package = "github.com/digital-asset/canton/go/ledger/api/v2/admin;adminv2";
 option csharp_namespace = "Com.Daml.Ledger.Api.V2.Admin";
 option java_outer_classname = "IdentityProviderConfigServiceOuterClass";
 option java_package = "com.daml.ledger.api.v2.admin";
@@ -37,20 +39,42 @@ option java_package = "com.daml.ledger.api.v2.admin";
 service IdentityProviderConfigService {
   // Create a new identity provider configuration.
   // The request will fail if the maximum allowed number of separate configurations is reached.
-  rpc CreateIdentityProviderConfig(CreateIdentityProviderConfigRequest) returns (CreateIdentityProviderConfigResponse);
+  rpc CreateIdentityProviderConfig(CreateIdentityProviderConfigRequest) returns (CreateIdentityProviderConfigResponse) {
+    option (google.api.http) = {
+      post: "/v2/idps"
+      body: "*"
+    };
+  }
 
   // Get the identity provider configuration data by id.
-  rpc GetIdentityProviderConfig(GetIdentityProviderConfigRequest) returns (GetIdentityProviderConfigResponse);
+  rpc GetIdentityProviderConfig(GetIdentityProviderConfigRequest) returns (GetIdentityProviderConfigResponse) {
+    option (google.api.http) = {
+      get: "/v2/idps/{identity_provider_id}"
+    };
+  }
 
   // Update selected modifiable attribute of an identity provider config resource described
   // by the ``IdentityProviderConfig`` message.
-  rpc UpdateIdentityProviderConfig(UpdateIdentityProviderConfigRequest) returns (UpdateIdentityProviderConfigResponse);
+  rpc UpdateIdentityProviderConfig(UpdateIdentityProviderConfigRequest) returns (UpdateIdentityProviderConfigResponse) {
+    option (google.api.http) = {
+      patch: "/v2/idps/{identity_provider_config.identity_provider_id}"
+      body: "*"
+    };
+  }
 
   // List all existing identity provider configurations.
-  rpc ListIdentityProviderConfigs(ListIdentityProviderConfigsRequest) returns (ListIdentityProviderConfigsResponse);
+  rpc ListIdentityProviderConfigs(ListIdentityProviderConfigsRequest) returns (ListIdentityProviderConfigsResponse) {
+    option (google.api.http) = {
+      get: "/v2/idps"
+    };
+  }
 
   // Delete an existing identity provider configuration.
-  rpc DeleteIdentityProviderConfig(DeleteIdentityProviderConfigRequest) returns (DeleteIdentityProviderConfigResponse);
+  rpc DeleteIdentityProviderConfig(DeleteIdentityProviderConfigRequest) returns (DeleteIdentityProviderConfigResponse) {
+    option (google.api.http) = {
+      delete: "/v2/idps/{identity_provider_id}"
+    };
+  }
 }
 
 message IdentityProviderConfig {

community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/admin/object_meta.proto

@@ -5,6 +5,7 @@ syntax = "proto3";
 
 package com.daml.ledger.api.v2.admin;
 
+option go_package = "github.com/digital-asset/canton/go/ledger/api/v2/admin;adminv2";
 option csharp_namespace = "Com.Daml.Ledger.Api.V2.Admin";
 option java_outer_classname = "ObjectMetaOuterClass";
 option java_package = "com.daml.ledger.api.v2.admin";

community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/admin/package_management_service.proto

@@ -6,8 +6,10 @@ syntax = "proto3";
 package com.daml.ledger.api.v2.admin;
 
 import "com/daml/ledger/api/v2/package_reference.proto";
+import "google/api/annotations.proto";
 import "google/protobuf/timestamp.proto";
 
+option go_package = "github.com/digital-asset/canton/go/ledger/api/v2/admin;adminv2";
 option csharp_namespace = "Com.Daml.Ledger.Api.V2.Admin";
 option java_outer_classname = "PackageManagementServiceOuterClass";
 option java_package = "com.daml.ledger.api.v2.admin";
@@ -27,18 +29,33 @@ service PackageManagementService {
   // If vetting is enabled in the request, the DAR is checked for upgrade compatibility
   // with the set of the already vetted packages on the target vetting synchronizer
   // See UploadDarFileRequest for details regarding vetting and the target vetting synchronizer.
-  rpc UploadDarFile(UploadDarFileRequest) returns (UploadDarFileResponse);
+  rpc UploadDarFile(UploadDarFileRequest) returns (UploadDarFileResponse) {
+    option (google.api.http) = {
+      post: "/v2/dars"
+      body: "*"
+    };
+  }
 
   // Validates the DAR and checks the upgrade compatibility of the DAR's packages
   // with the set of the already vetted packages on the target vetting synchronizer.
   // See ValidateDarFileRequest for details regarding the target vetting synchronizer.
   //
   // The operation has no effect on the state of the participant or the Canton ledger:
   // the DAR payload and its packages are not persisted neither are the packages vetted.
-  rpc ValidateDarFile(ValidateDarFileRequest) returns (ValidateDarFileResponse);
+  rpc ValidateDarFile(ValidateDarFileRequest) returns (ValidateDarFileResponse) {
+    option (google.api.http) = {
+      post: "/v2/dars/validate"
+      body: "*"
+    };
+  }
 
   // Update the vetted packages of this participant
-  rpc UpdateVettedPackages(UpdateVettedPackagesRequest) returns (UpdateVettedPackagesResponse);
+  rpc UpdateVettedPackages(UpdateVettedPackagesRequest) returns (UpdateVettedPackagesResponse) {
+    option (google.api.http) = {
+      post: "/v2/package-vetting/update"
+      body: "*"
+    };
+  }
 }
 
 message ListKnownPackagesRequest {}

community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/admin/participant_pruning_service.proto

@@ -5,6 +5,7 @@ syntax = "proto3";
 
 package com.daml.ledger.api.v2.admin;
 
+option go_package = "github.com/digital-asset/canton/go/ledger/api/v2/admin;adminv2";
 option csharp_namespace = "Com.Daml.Ledger.Api.V2.Admin";
 option java_outer_classname = "ParticipantPruningServiceOuterClass";
 option java_package = "com.daml.ledger.api.v2.admin";

community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/admin/party_management_service.proto

@@ -7,8 +7,10 @@ package com.daml.ledger.api.v2.admin;
 
 import "com/daml/ledger/api/v2/admin/object_meta.proto";
 import "com/daml/ledger/api/v2/crypto.proto";
+import "google/api/annotations.proto";
 import "google/protobuf/field_mask.proto";
 
+option go_package = "github.com/digital-asset/canton/go/ledger/api/v2/admin;adminv2";
 option csharp_namespace = "Com.Daml.Ledger.Api.V2.Admin";
 option java_outer_classname = "PartyManagementServiceOuterClass";
 option java_package = "com.daml.ledger.api.v2.admin";
@@ -39,16 +41,28 @@ service PartyManagementService {
   // All horizontally scaled replicas should return the same id.
   // daml-on-kv-ledger: returns an identifier supplied on command line at launch time
   // canton: returns globally unique identifier of the participant
-  rpc GetParticipantId(GetParticipantIdRequest) returns (GetParticipantIdResponse);
+  rpc GetParticipantId(GetParticipantIdRequest) returns (GetParticipantIdResponse) {
+    option (google.api.http) = {
+      get: "/v2/parties/participant-id"
+    };
+  }
 
   // Get the party details of the given parties. Only known parties will be
   // returned in the list.
-  rpc GetParties(GetPartiesRequest) returns (GetPartiesResponse);
+  rpc GetParties(GetPartiesRequest) returns (GetPartiesResponse) {
+    option (google.api.http) = {
+      get: "/v2/parties/{parties}"
+    };
+  }
 
   // List the parties known by the participant.
   // The list returned contains parties whose ledger access is facilitated by
   // the participant and the ones maintained elsewhere.
-  rpc ListKnownParties(ListKnownPartiesRequest) returns (ListKnownPartiesResponse);
+  rpc ListKnownParties(ListKnownPartiesRequest) returns (ListKnownPartiesResponse) {
+    option (google.api.http) = {
+      get: "/v2/parties"
+    };
+  }
 
   // Allocates a new party on a ledger and adds it to the set managed by the participant.
   // Caller specifies a party identifier suggestion, the actual identifier
@@ -67,7 +81,12 @@ service PartyManagementService {
   // is richer than the surface protocol, the arguments take implicit values
   // The party identifier suggestion must be a valid party name. Party names are required to be non-empty US-ASCII strings built from letters, digits, space,
   // colon, minus and underscore limited to 255 chars
-  rpc AllocateParty(AllocatePartyRequest) returns (AllocatePartyResponse);
+  rpc AllocateParty(AllocatePartyRequest) returns (AllocatePartyResponse) {
+    option (google.api.http) = {
+      post: "/v2/parties"
+      body: "*"
+    };
+  }
 
   // The external party must be hosted (at least) on this node with either confirmation or observation permissions
   // It can optionally be hosted on other nodes (then called a multi-hosted party).
@@ -78,11 +97,21 @@ service PartyManagementService {
   // In the simple case of a non-multi hosted, non-decentralized party, the RPC will return once the party is
   // effectively allocated and ready to use, similarly to the AllocateParty behavior.
   // For more complex scenarios applications may need to query the party status explicitly (only through the admin API as of now).
-  rpc AllocateExternalParty(AllocateExternalPartyRequest) returns (AllocateExternalPartyResponse);
+  rpc AllocateExternalParty(AllocateExternalPartyRequest) returns (AllocateExternalPartyResponse) {
+    option (google.api.http) = {
+      post: "/v2/parties/external/allocate"
+      body: "*"
+    };
+  }
 
   // Update selected modifiable participant-local attributes of a party details resource.
   // Can update the participant's local information for local parties.
-  rpc UpdatePartyDetails(UpdatePartyDetailsRequest) returns (UpdatePartyDetailsResponse);
+  rpc UpdatePartyDetails(UpdatePartyDetailsRequest) returns (UpdatePartyDetailsResponse) {
+    option (google.api.http) = {
+      patch: "/v2/parties/{party_details.party}"
+      body: "*"
+    };
+  }
 
   // Update the assignment of a party from one IDP to another.
   rpc UpdatePartyIdentityProviderId(UpdatePartyIdentityProviderIdRequest) returns (UpdatePartyIdentityProviderIdResponse);
@@ -93,7 +122,12 @@ service PartyManagementService {
   // Note that this request will create a normal namespace using the same key for the
   // identity as for signing. More elaborate schemes such as multi-signature
   // or decentralized parties require you to construct the topology transactions yourself.
-  rpc GenerateExternalPartyTopology(GenerateExternalPartyTopologyRequest) returns (GenerateExternalPartyTopologyResponse);
+  rpc GenerateExternalPartyTopology(GenerateExternalPartyTopologyRequest) returns (GenerateExternalPartyTopologyResponse) {
+    option (google.api.http) = {
+      post: "/v2/parties/external/generate-topology"
+      body: "*"
+    };
+  }
 }
 
 // Required authorization: ``HasRight(ParticipantAdmin)``

community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/admin/user_management_service.proto

@@ -6,8 +6,10 @@ syntax = "proto3";
 package com.daml.ledger.api.v2.admin;
 
 import "com/daml/ledger/api/v2/admin/object_meta.proto";
+import "google/api/annotations.proto";
 import "google/protobuf/field_mask.proto";
 
+option go_package = "github.com/digital-asset/canton/go/ledger/api/v2/admin;adminv2";
 option csharp_namespace = "Com.Daml.Ledger.Api.V2.Admin";
 option java_outer_classname = "UserManagementServiceOuterClass";
 option java_package = "com.daml.ledger.api.v2.admin";
@@ -42,33 +44,74 @@ option java_package = "com.daml.ledger.api.v2.admin";
 // In order to grant or revoke user rights use ``GrantRights' and ``RevokeRights`` RPCs.
 service UserManagementService {
   // Create a new user.
-  rpc CreateUser(CreateUserRequest) returns (CreateUserResponse);
+  rpc CreateUser(CreateUserRequest) returns (CreateUserResponse) {
+    option (google.api.http) = {
+      post: "/v2/users"
+      body: "*"
+    };
+  }
 
   // Get the user data of a specific user or the authenticated user.
-  rpc GetUser(GetUserRequest) returns (GetUserResponse);
+  rpc GetUser(GetUserRequest) returns (GetUserResponse) {
+    option (google.api.http) = {
+      get: "/v2/users/{user_id}"
+    };
+  }
 
   // Update selected modifiable attribute of a user resource described by the ``User`` message.
-  rpc UpdateUser(UpdateUserRequest) returns (UpdateUserResponse);
+  rpc UpdateUser(UpdateUserRequest) returns (UpdateUserResponse) {
+    option (google.api.http) = {
+      patch: "/v2/users/{user.id}"
+      body: "*"
+    };
+  }
 
   // Delete an existing user and all its rights.
-  rpc DeleteUser(DeleteUserRequest) returns (DeleteUserResponse);
+  rpc DeleteUser(DeleteUserRequest) returns (DeleteUserResponse) {
+    option (google.api.http) = {
+      delete: "/v2/users/{user_id}"
+    };
+  }
 
   // List all existing users.
-  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse);
+  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse) {
+    option (google.api.http) = {
+      get: "/v2/users"
+    };
+  }
 
   // Grant rights to a user.
   // Granting rights does not affect the resource version of the corresponding user.
-  rpc GrantUserRights(GrantUserRightsRequest) returns (GrantUserRightsResponse);
+  rpc GrantUserRights(GrantUserRightsRequest) returns (GrantUserRightsResponse) {
+    option (google.api.http) = {
+      post: "/v2/users/{user_id}/rights"
+      body: "*"
+    };
+  }
 
   // Revoke rights from a user.
   // Revoking rights does not affect the resource version of the corresponding user.
-  rpc RevokeUserRights(RevokeUserRightsRequest) returns (RevokeUserRightsResponse);
+  rpc RevokeUserRights(RevokeUserRightsRequest) returns (RevokeUserRightsResponse) {
+    option (google.api.http) = {
+      patch: "/v2/users/{user_id}/rights"
+      body: "*"
+    };
+  }
 
   // List the set of all rights granted to a user.
-  rpc ListUserRights(ListUserRightsRequest) returns (ListUserRightsResponse);
+  rpc ListUserRights(ListUserRightsRequest) returns (ListUserRightsResponse) {
+    option (google.api.http) = {
+      get: "/v2/users/{user_id}/rights"
+    };
+  }
 
   // Update the assignment of a user from one IDP to another.
-  rpc UpdateUserIdentityProviderId(UpdateUserIdentityProviderIdRequest) returns (UpdateUserIdentityProviderIdResponse);
+  rpc UpdateUserIdentityProviderId(UpdateUserIdentityProviderIdRequest) returns (UpdateUserIdentityProviderIdResponse) {
+    option (google.api.http) = {
+      patch: "/v2/users/{user_id}/identity-provider-id"
+      body: "*"
+    };
+  }
 }
 
 // Users and rights

community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/command_completion_service.proto

@@ -7,7 +7,9 @@ package com.daml.ledger.api.v2;
 
 import "com/daml/ledger/api/v2/completion.proto";
 import "com/daml/ledger/api/v2/offset_checkpoint.proto";
+import "google/api/annotations.proto";
 
+option go_package = "github.com/digital-asset/canton/go/ledger/api/v2;ledgerapiv2";
 option csharp_namespace = "Com.Daml.Ledger.Api.V2";
 option java_outer_classname = "CommandCompletionServiceOuterClass";
 option java_package = "com.daml.ledger.api.v2";
@@ -29,7 +31,12 @@ option java_package = "com.daml.ledger.api.v2";
 service CommandCompletionService {
   // Deprecated: please use ``GetCompletions`` instead.
   // Subscribe to command completion events.
-  rpc CompletionStream(CompletionStreamRequest) returns (stream CompletionStreamResponse);
+  rpc CompletionStream(CompletionStreamRequest) returns (stream CompletionStreamResponse) {
+    option (google.api.http) = {
+      post: "/v2/commands/completions"
+      body: "*"
+    };
+  }
 
   // Subscribe to command completion events.
   // This streaming endpoint provides more flexibility in filtering than the predecessor ``CompletionStream``.

community/ledger-api-proto/src/main/protobuf/com/daml/ledger/api/v2/command_service.proto

@@ -10,7 +10,9 @@ import "com/daml/ledger/api/v2/reassignment.proto";
 import "com/daml/ledger/api/v2/reassignment_commands.proto";
 import "com/daml/ledger/api/v2/transaction.proto";
 import "com/daml/ledger/api/v2/transaction_filter.proto";
+import "google/api/annotations.proto";
 
+option go_package = "github.com/digital-asset/canton/go/ledger/api/v2;ledgerapiv2";
 option csharp_namespace = "Com.Daml.Ledger.Api.V2";
 option java_outer_classname = "CommandServiceOuterClass";
 option java_package = "com.daml.ledger.api.v2";
@@ -23,15 +25,30 @@ option java_package = "com.daml.ledger.api.v2";
 service CommandService {
   // Submits a single composite command and waits for its result.
   // Propagates the gRPC error of failed submissions including Daml interpretation errors.
-  rpc SubmitAndWait(SubmitAndWaitRequest) returns (SubmitAndWaitResponse);
+  rpc SubmitAndWait(SubmitAndWaitRequest) returns (SubmitAndWaitResponse) {
+    option (google.api.http) = {
+      post: "/v2/commands/submit-and-wait"
+      body: "commands"
+    };
+  }
 
   // Submits a single composite command, waits for its result, and returns the transaction.
   // Propagates the gRPC error of failed submissions including Daml interpretation errors.
-  rpc SubmitAndWaitForTransaction(SubmitAndWaitForTransactionRequest) returns (SubmitAndWaitForTransactionResponse);
+  rpc SubmitAndWaitForTransaction(SubmitAndWaitForTransactionRequest) returns (SubmitAndWaitForTransactionResponse) {
+    option (google.api.http) = {
+      post: "/v2/commands/submit-and-wait-for-transaction"
+      body: "*"
+    };
+  }
 
   // Submits a single composite reassignment command, waits for its result, and returns the reassignment.
   // Propagates the gRPC error of failed submission.
-  rpc SubmitAndWaitForReassignment(SubmitAndWaitForReassignmentRequest) returns (SubmitAndWaitForReassignmentResponse);
+  rpc SubmitAndWaitForReassignment(SubmitAndWaitForReassignmentRequest) returns (SubmitAndWaitForReassignmentResponse) {
+    option (google.api.http) = {
+      post: "/v2/commands/submit-and-wait-for-reassignment"
+      body: "*"
+    };
+  }
 }
 
 // These commands are executed as a single atomic transaction.