Tidy up /template APIs

.gitattributes

@@ -1,4 +1,6 @@
 # Collapse the diff of generated files in github by default
 **/*.swagger.json linguist-generated=true
 **/*.pb.* linguist-generated=true
+**/*.swagger.json merge=proto
+**/*.pb.* merge=proto
 

Makefile

@@ -256,7 +256,6 @@ swagger-docs:
 user-guide-apis:
 	cp cmd/clusters-service/api/cluster_services.swagger.json ../weave-gitops/website/static/swagger/
 	cp api/gitauth/gitauth.swagger.json ../weave-gitops/website/static/swagger/
-	cp api/gitopssets/gitopssets.swagger.json ../weave-gitops/website/static/swagger/
 	cp api/pipelines/pipelines.swagger.json ../weave-gitops/website/static/swagger/
 	cp api/query/query.swagger.json ../weave-gitops/website/static/swagger/
 	cp api/terraform/terraform.swagger.json ../weave-gitops/website/static/swagger/

api/gitauth/gitauth.proto

@@ -28,7 +28,13 @@ option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
  */
 service GitAuth {
     /**
-    * Wrap a git provider token in a JWT
+    * Wrap an existing git provider token in a JWT
+    *
+    * If you already have an OAuth token, or a Personal Access Token, it can be
+    * manually wrapped in a JWT using this endpoint.
+    *
+    * The resulting JWT can be included in requests to other API endpoint
+    * that interact with the Git provider (e.g. creating a pull request from a template).
     */
     rpc Authenticate(AuthenticateRequest) returns (AuthenticateResponse) {
         option (google.api.http) = {
@@ -69,7 +75,7 @@ service GitAuth {
     * Get the URL to initiate a GitLab OAuth flow.
     *
     * The user must browse to the returned URL to authorize the OAuth callback
-    * to the GitOps UI.
+    * to the Weave GitOps UI.
     * See the GitLab OAuth docs for more more information:
     * https://docs.gitlab.com/ee/api/oauth2.html#supported-oauth-20-flows
     */
@@ -93,7 +99,7 @@ service GitAuth {
     /**
     * Exchange a Bitbucket Server code obtained via OAuth callback.
     *
-    * The returned token is useable for authentication with the GitOps server only.
+    * The returned token is useable for authentication with the Weave GitOps server only.
     */
     rpc AuthorizeBitbucketServer (AuthorizeBitbucketServerRequest)
         returns (AuthorizeBitbucketServerResponse) {
@@ -106,7 +112,7 @@ service GitAuth {
     /**
     * Exchange a GitLab code obtained via OAuth callback.
     *
-    * The returned token is useable for authentication with the GitOps server only.
+    * The returned token is useable for authentication with the Weave GitOps server only.
     * See the GitLab OAuth docs for more more information:
     * https://docs.gitlab.com/ee/api/oauth2.html#supported-oauth-20-flows
     */
@@ -164,13 +170,14 @@ service GitAuth {
 }
 
 message AuthenticateRequest {
-    string provider_name = 1;  // The name of the git provider
-    string access_token  = 2;  // The token of the git provider
+    // The name of the git provider. E.g. "github", "gitlab", "bitbucketserver", "azuredevops".
+    string provider_name = 1;
+    // The token of the git provider.
+    string access_token  = 2;
 }
 
 message AuthenticateResponse {
-    /* The jwt token that was generated using git provider name
-    and git provider token */
+    // The jwt token that was generated using git provider name and git provider token.
     string token = 1;
 }
 
@@ -179,28 +186,29 @@ message GetGithubDeviceCodeRequest {
 }
 
 message GetGithubDeviceCodeResponse {
-    // The Github Device Flow code that will be shown to the user
+    // The Github Device Flow code that will be shown to the user.
     string user_code      = 1;
-    string device_code    = 2; // A code that uniquely identifies a device
-    // The URI that the user will visit to complete the flow
+    // A code that uniquely identifies a device.
+    string device_code    = 2;
+    // The URI that the user will visit to complete the flow.
     string validation_uri = 3;
-    int32  interval      = 4; // How often the client should retry the request
+    // How often the client should retry the request.
+    int32  interval      = 4;
 }
 
 message GetGithubAuthStatusRequest {
-    // The deviceCode returned from a GetGithubDeviceCodeResponse
+    // The deviceCode returned from a GetGithubDeviceCodeResponse.
     string device_code = 1;
 }
 
 message GetGithubAuthStatusResponse {
     // An access token that can be used to interact with the Weave GitOps API.
     string access_token = 1;
-    string error       = 2; // An error message.
+    // An error message.
+    string error       = 2;
 }
 
-/**
- * GitProvider enum defines the Git provider used in the GitAuth API.
- */
+// GitProvider enum defines the Git provider used in the GitAuth API.
 enum GitProvider {
     Unknown         = 0;
     GitHub          = 1;
@@ -210,18 +218,21 @@ enum GitProvider {
 }
 
 message ParseRepoURLRequest {
-    string url = 1; // The URL to be parsed
+    // The URL to be parsed.
+    string url = 1;
 }
 
 message ParseRepoURLResponse {
-    string      name     = 1; // The name of the git repository
-    GitProvider provider = 2; // The GitProvider for the repository
-    // The person or organization to which this repo belongs
+    // The name of the git repository.
+    string      name     = 1;
+    // The GitProvider for the repository.
+    GitProvider provider = 2;
+    // The person or organization to which this repo belongs.
     string      owner    = 3;
 }
 
 message GetGitlabAuthURLRequest {
-    // The URI that GitLab will use to send users back to GitOps.
+    // The URI that GitLab will use to send users back to Weave GitOps.
     string redirect_uri = 1;
 }
 
@@ -231,13 +242,14 @@ message GetGitlabAuthURLResponse {
 }
 
 message AuthorizeGitlabRequest {
-    // The challenge code obtained from the OAuth callback
+    // The challenge code obtained from the OAuth callback.
     string code        = 1;
-    string redirect_uri = 2; // The redirect URI that originated the OAuth flow
+    // The redirect URI that originated the OAuth flow.
+    string redirect_uri = 2;
 }
 
 message AuthorizeGitlabResponse {
-    // A token that can be used to authenticate the GitOps API server.
+    // A token that can be used to authenticate the Weave GitOps API server.
     string token = 1;
 }
 
@@ -250,31 +262,31 @@ message ValidateProviderTokenResponse {
 }
 
 message GetBitbucketServerAuthURLRequest {
-    // The URI that Bitbucket Server will use to send users back to GitOps.
+    // The URI that Bitbucket Server will use to send users back to Weave GitOps.
     string redirect_uri = 1;
 }
 
 message GetBitbucketServerAuthURLResponse {
-    /* The URL that users must visit
-    to authorize BitBucket Server authentication.*/
+    // The URL that users must visit to authorize BitBucket Server authentication.
     string url = 1;
 }
 
 message AuthorizeBitbucketServerRequest {
-    // The challenge code obtained from the OAuth callback
+    // The challenge code obtained from the OAuth callback.
     string code        = 1;
-    // The state parameter provided in the authorization URL
+    // The state parameter provided in the authorization URL.
     string state       = 2; 
-    string redirect_uri = 3; // The redirect URI that originated the OAuth flow
+    // The redirect URI that originated the OAuth flow.
+    string redirect_uri = 3;
 }
 
 message AuthorizeBitbucketServerResponse {
-    // A token that can be used to authenticate the GitOps API server.
+    // A token that can be used to authenticate the Weave GitOps API server.
     string token = 1;
 }
 
 message GetAzureDevOpsAuthURLRequest {
-    // The URI that Azure DevOps will use to send users back to GitOps.
+    // The URI that Azure DevOps will use to send users back to Weave GitOps.
     string redirect_uri = 1;
 }
 
@@ -284,14 +296,15 @@ message GetAzureDevOpsAuthURLResponse {
 }
 
 message AuthorizeAzureDevOpsRequest {
-    // The challenge code obtained from the OAuth callback
+    // The challenge code obtained from the OAuth callback.
     string code        = 1;
-    // The state parameter provided in the authorization URL
+    // The state parameter provided in the authorization URL.
     string state       = 2;
-    string redirect_uri = 3; // The redirect URI that originated the OAuth flow
+    // The redirect URI that originated the OAuth flow.
+    string redirect_uri = 3;
 }
 
 message AuthorizeAzureDevOpsResponse {
-    // A token that can be used to authenticate the GitOps API server.
+    // A token that can be used to authenticate the Weave GitOps API server.
     string token = 1; 
 }