PMM-12985 Apply v3 API infra modifications and update docs (#3207)

* PMM-12985 Apply API infra modifications * PMM-12985 Apply API infra modifications * PMM-12985 add --version flag to spec sync * PMM-12985 change the slug name * PMM-12985 migrate from IDs to slugs * PMM-12985 update the intro with links * PMM-12985 update inventory overview * Update docs/api/inventory/overview.md Co-authored-by: Catalina A <[email protected]> * Update docs/api/inventory/overview.md Co-authored-by: Catalina A <[email protected]> * Update api/server/v1/server.proto Co-authored-by: Catalina A <[email protected]> * Update docs/api/access-control/overview.md Co-authored-by: Catalina A <[email protected]> * Update docs/api/advisor-api/advisors-and-advisor-checks.md Co-authored-by: Catalina A <[email protected]> * Update docs/api/advisor-api/overview.md Co-authored-by: Catalina A <[email protected]> * Update docs/api/advisor-api/overview.md Co-authored-by: Catalina A <[email protected]> * Update docs/api/inventory/overview.md Co-authored-by: Catalina A <[email protected]> * Update docs/api/advisor-api/overview.md Co-authored-by: Catalina A <[email protected]> * PMM-12985 Regenerate. --------- Co-authored-by: Catalina A <[email protected]> Co-authored-by: Nurlan Moldomurov <[email protected]>
percona · Nov 5, 2024 · 8e92466 · 8e92466
1 parent 7d2c4fd
commit 8e92466
Show file tree

Hide file tree

Showing 41 changed files with 444 additions and 366 deletions.
diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
@@ -12,7 +12,7 @@ on:
 
 jobs:
   sync:
-    name: Sync
+    name: Sync API Docs
     runs-on: ubuntu-22.04
 
     steps:
@@ -29,11 +29,12 @@ jobs:
           echo "VERSION=$VERSION" >> $GITHUB_ENV
           echo "ID=$ID" >> $GITHUB_ENV
 
-      - name: Provision rdme
-        run: npm install -g rdme
-
       - name: Sync API spec
-        run: rdme openapi ./api/swagger/swagger.json --id=${{ env.ID }} --key=${{ secrets.README_TOKEN }}
+        uses: readmeio/rdme@v8
+        with:
+          rdme: openapi ./api/swagger/swagger.json --version=${{ env.VERSION }} --id=${{ env.ID }} --key=${{ secrets.README_TOKEN }}
 
       - name: Sync Markdown docs
-        run: rdme docs docs/api --version=${{ env.VERSION }} --key=${{ secrets.README_TOKEN }}
+        uses: readmeio/rdme@v8
+        with: 
+          rdme: docs ./docs/api --version=${{ env.VERSION }} --key=${{ secrets.README_TOKEN }}
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -99,7 +99,7 @@ jobs:
           fi
 
           # One may need to suppress passing to reviewdog because of https://github.com/reviewdog/reviewdog/issues/1696
-          echo "$out" | bin/reviewdog -f=buf -reporter=github-pr-review -fail-on-error=true
+          echo "$out" | bin/reviewdog -f=buf -reporter=github-pr-review -fail-level=error
 
       - name: Run code linters
         uses: reviewdog/action-golangci-lint@v2
@@ -126,7 +126,7 @@ jobs:
             exit $exit_code
           fi
 
-          echo "$out" | bin/reviewdog -f=go-consistent -reporter=github-pr-review -fail-on-error=true
+          echo "$out" | bin/reviewdog -f=go-consistent -reporter=github-pr-review -fail-level=error
 
       - name: Test common API
         run: make test-common

diff --git a/api/advisors/v1/advisors.pb.go b/api/advisors/v1/advisors.pb.go
diff --git a/api/advisors/v1/advisors.proto b/api/advisors/v1/advisors.proto
@@ -177,7 +177,7 @@ service AdvisorService {
   rpc GetFailedChecks(GetFailedChecksRequest) returns (GetFailedChecksResponse) {
     option (google.api.http) = {get: "/v1/advisors/checks/failed"};
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
-      summary: "Get Failed Checks"
+      summary: "Get Failed Advisor Checks"
       description: "Returns the latest check results for a given service."
     };
   }
@@ -196,15 +196,15 @@ service AdvisorService {
   rpc ListAdvisorChecks(ListAdvisorChecksRequest) returns (ListAdvisorChecksResponse) {
     option (google.api.http) = {get: "/v1/advisors/checks"};
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
-      summary: "List advisor checks"
+      summary: "List Advisor Checks"
       description: "List advisor checks available to the user."
     };
   }
   // ListAdvisors returns a list of advisors available for the user.
   rpc ListAdvisors(ListAdvisorsRequest) returns (ListAdvisorsResponse) {
     option (google.api.http) = {get: "/v1/advisors"};
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
-      summary: "List advisors"
+      summary: "List Advisors"
       description: "List advisors available to the user."
     };
   }

diff --git a/api/advisors/v1/json/client/advisor_service/advisor_service_client.go b/api/advisors/v1/json/client/advisor_service/advisor_service_client.go
diff --git a/api/advisors/v1/json/v1.json b/api/advisors/v1/json/v1.json
@@ -21,7 +21,7 @@
         "tags": [
           "AdvisorService"
         ],
-        "summary": "List advisors",
+        "summary": "List Advisors",
         "operationId": "ListAdvisors",
         "responses": {
           "200": {
@@ -160,7 +160,7 @@
         "tags": [
           "AdvisorService"
         ],
-        "summary": "List advisor checks",
+        "summary": "List Advisor Checks",
         "operationId": "ListAdvisorChecks",
         "responses": {
           "200": {
@@ -264,7 +264,7 @@
         "tags": [
           "AdvisorService"
         ],
-        "summary": "Get Failed Checks",
+        "summary": "Get Failed Advisor Checks",
         "operationId": "GetFailedChecks",
         "parameters": [
           {

diff --git a/api/server/v1/json/client/server_service/server_service_client.go b/api/server/v1/json/client/server_service/server_service_client.go
diff --git a/api/server/v1/json/v1.json b/api/server/v1/json/v1.json
@@ -798,11 +798,11 @@
     },
     "/v1/server/updates/changelogs": {
       "get": {
-        "description": "List all the changes between the installed version and the latest available version",
+        "description": "Display a changelog comparing the installed version to the latest available version.",
         "tags": [
           "ServerService"
         ],
-        "summary": "List all the changes between the installed version and the latest available version",
+        "summary": "Get the changelog",
         "operationId": "ListChangeLogs",
         "responses": {
           "200": {

diff --git a/api/server/v1/server.pb.go b/api/server/v1/server.pb.go
diff --git a/api/server/v1/server.proto b/api/server/v1/server.proto
@@ -250,12 +250,12 @@ service ServerService {
       description: "Checks for available PMM Server updates."
     };
   }
-
+  // ListChangeLogs delivers the changelog.
   rpc ListChangeLogs(ListChangeLogsRequest) returns (ListChangeLogsResponse) {
     option (google.api.http) = {get: "/v1/server/updates/changelogs"};
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
-      summary: "List all the changes between the installed version and the latest available version"
-      description: "List all the changes between the installed version and the latest available version"
+      summary: "Get the changelog"
+      description: "Display a changelog comparing the installed version to the latest available version."
     };
   }
   // StartUpdate starts PMM Server update.