chore: Manage the api spec file in the docs directory (#2143) (#3425)

Co-authored-by: Sion Kang <[email protected]>

.github/labeler.yml

@@ -7,8 +7,6 @@ area:docs:
 - changed-files:
   - any-glob-to-any-file:
     - 'docs/**/*'
-    - 'src/ai/backend/manager/api/**/*.py'
-    - 'src/ai/backend/manager/models/gql.py'
 
 comp:storage-proxy:
 - changed-files:

.github/workflows/update-api-schema.yml

@@ -4,9 +4,10 @@ on:
   pull_request:
     paths:
       - 'src/ai/backend/manager/models/**'
+      - 'src/ai/backend/manager/api/**'
 
 jobs:
-  graphql-updated:
+  api-updated:
     runs-on: ubuntu-latest
     permissions:
       contents: write
@@ -52,27 +53,28 @@ jobs:
         cache-lmdb-store: 'true'
     - name: Pants export
       run: pants export --resolve=python-default
-    - name: Create GraphQL schema dump
+    - name: Create api schema dump
       run: |
-        ./backend.ai mgr api dump-gql-schema --output src/ai/backend/manager/api/schema.graphql
-    - name: Extract the author information
-      id: get_author_info
+        ./backend.ai mgr api dump-gql-schema --output docs/manager/graphql-reference/schema.graphql
+        ./backend.ai mgr api dump-openapi --output docs/manager/rest-reference/openapi.json
+    - name: Make commit message for changing change log file
       run: |
+        git add docs/manager/graphql-reference/schema.graphql
+        git add docs/manager/rest-reference/openapi.json
         author_name=$(git show -q --pretty='format:%an')
         author_email=$(git show -q --pretty='format:%ae')
         git config user.email "$author_email"
         git config user.name "$author_name"
         if [ -n "$(git diff --staged)" ]; then
           git commit \
-            -m "chore: update GraphQL schema dump" \
+            -m "chore: update api schema dump" \
             --author="$author_name <$author_email>" \
             --trailer "Co-authored-by: octodog <[email protected]>"
           git push
         fi
 
   graphql-inspector:
-    needs: graphql-updated
-    name: Check Schema
+    needs: api-updated
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -82,6 +84,6 @@ jobs:
       - uses: actions/checkout@v4
       - uses: kamilkisiela/graphql-inspector@release-1717403590269
         with:
-          schema: '${{ github.base_ref }}:src/ai/backend/manager/api/schema.graphql'
+          schema: '${{ github.base_ref }}:docs/manager/graphql-reference/schema.graphql'
           rules: |
             gql-inspector-checker.js

.readthedocs.yaml

@@ -16,8 +16,6 @@ build:
           exit 183;
         fi
     pre_build:
-      # Auto-generate REST API reference
-      - PYTHONPATH="src" python -m ai.backend.manager.openapi -o docs/manager/rest-reference/openapi.json
       - |
         if [ "$READTHEDOCS_VERSION_TYPE" != "external" ];
         then

docs/README.md

@@ -26,11 +26,16 @@ $ pip install -U -r requirements.txt
 
 
 ## Building API Reference JSON file
+REST API
 ```console
 $ ./backend.ai mgr api dump-openapi --output docs/manager/rest-reference/openapi.json
 ```
+Graphql API
+```console
+$ ./backend.ai mgr api dump-graphql-schema --output docs/manager/graphql-reference/schema.graphql
+```
 This script must be executed on behalf of the virtual environment managed by pants, not by the venv for the sphinx.
-Generated OpenAPI JSON file will be located at under `manager/rest-reference/openapi.json`.
+Generated OpenAPI file will be located at under `manager/rest-reference/openapi.json` and `manager/graphql-reference/schema.graphql`.
 
 
 ## Building HTML document
@@ -166,7 +171,7 @@ to interact and inspect the Backend.AI Manager's GraphQL API.
 3. From your web browser, navigate to `/spec/openapi` under proxy server set up at step 2.
    Enjoy auto-completion and schema introspection of Backend.AI admin API!
 
-### Interactive GraphQL browser
+### Interactive GraphQL API browser
 
 You may use [GraphiQL](https://github.com/graphql/graphiql/tree/main/packages/graphiql#graphiql)
 to interact and inspect the Backend.AI Manager's GraphQL API.