Cleanup /api proto (#3370)

* cleanup apis * Re-gen after merge in main * gitopssets: remove cluster_name from path, add docs * terraform-objects: remove cluster from path, add docs * Sync/suspend use PATCH --------- Co-authored-by: Simon Howe <[email protected]> Co-authored-by: Simon <[email protected]>
weaveworks · Nov 2, 2023 · 4e702bd · 4e702bd
1 parent b7018a1
commit 4e702bd
Show file tree

Hide file tree

Showing 30 changed files with 2,226 additions and 1,531 deletions.
diff --git a/Makefile b/Makefile
@@ -252,6 +252,15 @@ swagger-docs:
 	-v $(CURRENT_DIR)/api:/usr/share/nginx/html/api \
 	swaggerapi/swagger-ui
 
+.PHONY: user-guide-apis
+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/
+
 
 FORCE:
 

diff --git a/api/gitauth/gitauth.proto b/api/gitauth/gitauth.proto
@@ -28,8 +28,7 @@ option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
  */
 service GitAuth {
     /**
-    * Authenticate generates jwt token using git provider name
-    * and git provider token arguments
+    * Wrap a git provider token in a JWT
     */
     rpc Authenticate(AuthenticateRequest) returns (AuthenticateResponse) {
         option (google.api.http) = {
@@ -39,35 +38,36 @@ service GitAuth {
     }
 
     /**
-    * GetGithubDeviceCode retrieves a temporary device code
-    * for Github authentication.
+    * Get a temporary device code for Github authentication
+    *
     * This code is used to start the Github device-flow.
     */
     rpc GetGithubDeviceCode(GetGithubDeviceCodeRequest)
         returns (GetGithubDeviceCodeResponse) {
         option (google.api.http) = {
-            get : "/v1/gitauth/auth_providers/github"
+            get : "/v1/gitauth/auth-providers/github"
         };
     }
 
     /**
-    * GetGithubAuthStatus gets the status of the Github device flow
-    * authentication requests. Once the user has completed
-    * the Github device flow, an access token will be returned.
+    * Get the status of the Github device flow authentication requests
+    *
+    * Once the user has completed the Github device flow, an access token will be returned.
     * This token will expire in 15 minutes,
     * after which the user will need to complete the flow again
     * to do Git Provider operations.
     */
     rpc GetGithubAuthStatus(GetGithubAuthStatusRequest)
         returns (GetGithubAuthStatusResponse) {
         option (google.api.http) = {
-            post : "/v1/gitauth/auth_providers/github/status"
+            post : "/v1/gitauth/auth-providers/github/status"
             body: "*"
         };
     }
 
     /**
-    * GetGitlabAuthURL returns the URL to initiate a GitLab OAuth PKCE flow.
+    * 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.
     * See the GitLab OAuth docs for more more information:
@@ -76,85 +76,88 @@ service GitAuth {
     rpc GetGitlabAuthURL(GetGitlabAuthURLRequest)
         returns (GetGitlabAuthURLResponse) {
         option (google.api.http) = {
-            get : "/v1/gitauth/auth_providers/gitlab"
+            get : "/v1/gitauth/auth-providers/gitlab"
         };
     }
 
     /**
+    * Get the URL to initiate a Bitbucket Server OAuth flow.
     */
     rpc GetBitbucketServerAuthURL(GetBitbucketServerAuthURLRequest)
         returns (GetBitbucketServerAuthURLResponse) {
         option (google.api.http) = {
-            get : "/v1/gitauth/auth_providers/bitbucketserver"
+            get : "/v1/gitauth/auth-providers/bitbucketserver"
         };
     }
 
     /**
+    * Exchange a Bitbucket Server code obtained via OAuth callback.
+    *
+    * The returned token is useable for authentication with the GitOps server only.
     */
     rpc AuthorizeBitbucketServer (AuthorizeBitbucketServerRequest)
         returns (AuthorizeBitbucketServerResponse) {
         option (google.api.http) = {
-            post : "/v1/gitauth/auth_providers/bitbucketserver/authorize"
+            post : "/v1/gitauth/auth-providers/bitbucketserver/authorize"
             body: "*"
         };
     }
 
     /**
-    * AuthorizeGitlab exchanges a GitLab code obtained via OAuth callback.
-    * The returned token is useable for authentication
-    * with the GitOps server only.
+    * Exchange a GitLab code obtained via OAuth callback.
+    *
+    * The returned token is useable for authentication with the GitOps server only.
     * See the GitLab OAuth docs for more more information:
     * https://docs.gitlab.com/ee/api/oauth2.html#supported-oauth-20-flows
     */
     rpc AuthorizeGitlab(AuthorizeGitlabRequest)
         returns (AuthorizeGitlabResponse) {
         option (google.api.http) = {
-            post : "/v1/gitauth/auth_providers/gitlab/authorize"
+            post : "/v1/gitauth/auth-providers/gitlab/authorize"
             body: "*"
         };
     }
 
     /**
-    * GetAzureDevOpsAuthURL returns the Azure DevOps authorization URL
-    * used to initiate the OAuth flow.
+    * Get the Azure DevOps authorization URL used to initiate the OAuth flow.
     */
     rpc GetAzureDevOpsAuthURL(GetAzureDevOpsAuthURLRequest)
         returns (GetAzureDevOpsAuthURLResponse) {
         option (google.api.http) = {
-            get : "/v1/gitauth/auth_providers/azuredevops"
+            get : "/v1/gitauth/auth-providers/azuredevops"
         };
     }
 
     /**
-    * AuthorizeAzureDevOps returns a token after a user authorizes
-    * Azure DevOps to grant access to their account
+    * Exchange an Azure DevOps code obtained via OAuth callback.
+    *
+    * Get a token after a user authorizes Azure DevOps to grant access to their account
     * on behalf of Weave GitOps Enterprise.
     */
     rpc AuthorizeAzureDevOps (AuthorizeAzureDevOpsRequest)
         returns (AuthorizeAzureDevOpsResponse) {
         option (google.api.http) = {
-            post : "/v1/gitauth/auth_providers/azuredevops/authorize"
+            post : "/v1/gitauth/auth-providers/azuredevops/authorize"
             body: "*"
         };
     }
 
     /**
-    * ParseRepoURL returns structured data about a git repository URL
+    * Get structured data about a git repository URL
     */
     rpc ParseRepoURL(ParseRepoURLRequest) returns(ParseRepoURLResponse) {
         option (google.api.http) = {
-            get : "/v1/gitauth/parse_repo_url"
+            get : "/v1/gitauth/parse-repo-url"
         };
     }
 
     /**
-    * ValidateProviderToken check to see if the git provider token
-    * is still valid
+    * Check if a git provider token is still valid
     */
     rpc ValidateProviderToken(ValidateProviderTokenRequest)
         returns (ValidateProviderTokenResponse) {
         option (google.api.http) = {
-            post : "/v1/gitauth/validate_token"
+            post : "/v1/gitauth/validate-token"
             body: "*"
         };
     }

diff --git a/api/gitauth/gitauth.swagger.json b/api/gitauth/gitauth.swagger.json
@@ -19,7 +19,7 @@
   "paths": {
     "/v1/authenticate/{providerName}": {
       "post": {
-        "summary": "Authenticate generates jwt token using git provider name\nand git provider token arguments",
+        "summary": "Wrap a git provider token in a JWT",
         "operationId": "GitAuth_Authenticate",
         "responses": {
           "200": {
@@ -63,9 +63,9 @@
         ]
       }
     },
-    "/v1/gitauth/auth_providers/azuredevops": {
+    "/v1/gitauth/auth-providers/azuredevops": {
       "get": {
-        "summary": "GetAzureDevOpsAuthURL returns the Azure DevOps authorization URL\nused to initiate the OAuth flow.",
+        "summary": "Get the Azure DevOps authorization URL used to initiate the OAuth flow.",
         "operationId": "GitAuth_GetAzureDevOpsAuthURL",
         "responses": {
           "200": {
@@ -95,9 +95,10 @@
         ]
       }
     },
-    "/v1/gitauth/auth_providers/azuredevops/authorize": {
+    "/v1/gitauth/auth-providers/azuredevops/authorize": {
       "post": {
-        "summary": "AuthorizeAzureDevOps returns a token after a user authorizes\nAzure DevOps to grant access to their account\non behalf of Weave GitOps Enterprise.",
+        "summary": "Exchange an Azure DevOps code obtained via OAuth callback.",
+        "description": "Get a token after a user authorizes Azure DevOps to grant access to their account\non behalf of Weave GitOps Enterprise.",
         "operationId": "GitAuth_AuthorizeAzureDevOps",
         "responses": {
           "200": {
@@ -128,8 +129,9 @@
         ]
       }
     },
-    "/v1/gitauth/auth_providers/bitbucketserver": {
+    "/v1/gitauth/auth-providers/bitbucketserver": {
       "get": {
+        "summary": "Get the URL to initiate a Bitbucket Server OAuth flow.",
         "operationId": "GitAuth_GetBitbucketServerAuthURL",
         "responses": {
           "200": {
@@ -159,8 +161,10 @@
         ]
       }
     },
-    "/v1/gitauth/auth_providers/bitbucketserver/authorize": {
+    "/v1/gitauth/auth-providers/bitbucketserver/authorize": {
       "post": {
+        "summary": "Exchange a Bitbucket Server code obtained via OAuth callback.",
+        "description": "The returned token is useable for authentication with the GitOps server only.",
         "operationId": "GitAuth_AuthorizeBitbucketServer",
         "responses": {
           "200": {
@@ -191,9 +195,10 @@
         ]
       }
     },
-    "/v1/gitauth/auth_providers/github": {
+    "/v1/gitauth/auth-providers/github": {
       "get": {
-        "summary": "GetGithubDeviceCode retrieves a temporary device code\nfor Github authentication.\nThis code is used to start the Github device-flow.",
+        "summary": "Get a temporary device code for Github authentication",
+        "description": "This code is used to start the Github device-flow.",
         "operationId": "GitAuth_GetGithubDeviceCode",
         "responses": {
           "200": {
@@ -214,9 +219,10 @@
         ]
       }
     },
-    "/v1/gitauth/auth_providers/github/status": {
+    "/v1/gitauth/auth-providers/github/status": {
       "post": {
-        "summary": "GetGithubAuthStatus gets the status of the Github device flow\nauthentication requests. Once the user has completed\nthe Github device flow, an access token will be returned.\nThis token will expire in 15 minutes,\nafter which the user will need to complete the flow again\nto do Git Provider operations.",
+        "summary": "Get the status of the Github device flow authentication requests",
+        "description": "Once the user has completed the Github device flow, an access token will be returned.\nThis token will expire in 15 minutes,\nafter which the user will need to complete the flow again\nto do Git Provider operations.",
         "operationId": "GitAuth_GetGithubAuthStatus",
         "responses": {
           "200": {
@@ -247,9 +253,10 @@
         ]
       }
     },
-    "/v1/gitauth/auth_providers/gitlab": {
+    "/v1/gitauth/auth-providers/gitlab": {
       "get": {
-        "summary": "GetGitlabAuthURL returns the URL to initiate a GitLab OAuth PKCE flow.\nThe user must browse to the returned URL to authorize the OAuth callback\nto the GitOps UI.\nSee the GitLab OAuth docs for more more information:\nhttps://docs.gitlab.com/ee/api/oauth2.html#supported-oauth-20-flows",
+        "summary": "Get the URL to initiate a GitLab OAuth flow.",
+        "description": "The user must browse to the returned URL to authorize the OAuth callback\nto the GitOps UI.\nSee the GitLab OAuth docs for more more information:\nhttps://docs.gitlab.com/ee/api/oauth2.html#supported-oauth-20-flows",
         "operationId": "GitAuth_GetGitlabAuthURL",
         "responses": {
           "200": {
@@ -279,9 +286,10 @@
         ]
       }
     },
-    "/v1/gitauth/auth_providers/gitlab/authorize": {
+    "/v1/gitauth/auth-providers/gitlab/authorize": {
       "post": {
-        "summary": "AuthorizeGitlab exchanges a GitLab code obtained via OAuth callback.\nThe returned token is useable for authentication\nwith the GitOps server only.\nSee the GitLab OAuth docs for more more information:\nhttps://docs.gitlab.com/ee/api/oauth2.html#supported-oauth-20-flows",
+        "summary": "Exchange a GitLab code obtained via OAuth callback.",
+        "description": "The returned token is useable for authentication with the GitOps server only.\nSee the GitLab OAuth docs for more more information:\nhttps://docs.gitlab.com/ee/api/oauth2.html#supported-oauth-20-flows",
         "operationId": "GitAuth_AuthorizeGitlab",
         "responses": {
           "200": {
@@ -312,9 +320,9 @@
         ]
       }
     },
-    "/v1/gitauth/parse_repo_url": {
+    "/v1/gitauth/parse-repo-url": {
       "get": {
-        "summary": "ParseRepoURL returns structured data about a git repository URL",
+        "summary": "Get structured data about a git repository URL",
         "operationId": "GitAuth_ParseRepoURL",
         "responses": {
           "200": {
@@ -344,9 +352,9 @@
         ]
       }
     },
-    "/v1/gitauth/validate_token": {
+    "/v1/gitauth/validate-token": {
       "post": {
-        "summary": "ValidateProviderToken check to see if the git provider token\nis still valid",
+        "summary": "Check if a git provider token is still valid",
         "operationId": "GitAuth_ValidateProviderToken",
         "responses": {
           "200": {