chore: add cube-cos-openapi submodule as single state of truth

[raven-pan]

What type of PR is this?

Chore / Refactor

Which issue(s) this PR fixes?

N/A — this is a housekeeping change to establish cube-cos-openapi as the single source of truth for API documentation.

What this PR does?

1. Adds bigstack-oss/cube-cos-openapi as a git submodule at cube-cos-openapi and cube-cos-openapi.
2. Replaces the hand-maintained 27K-line JSON const in docs.go with a //go:embed docs.json approach — the spec is now embedded from a generated file at build time.
3. Adds a generateApiDocs Taskfile task (yq -o=json -I=4 docs.yaml > api/docs.json) and wires it as a dependency of buildLocalBinary and runLocalDevApi.
4. Removes the old diffApiDocs check task (no longer needed since the JSON is generated).
5. Updates developer documentation to describe the new workflow.

Benefits:

• docs.yaml is the authoritative OpenAPI 3.0 spec — edit YAML, not JSON.
• Build generates docs.json fresh every time, preventing drift.

Test results (optional)

1). make sure the api docs have been updated

• task generateApiDocs produces docs.json from docs.yaml
• Swagger UI serves correctly at /api/v1/datacenters/{dataCenter}/apidocs/index.html

2). make sure the api works properly

• task deployRemoteDevApi and task vet pass cleanly

[arasHi87]

1. Orphan submodule path breaks fresh-clone builds

.gitmodules registers only api/cube-cos-openapi, but there's a second gitlink
cube-cos-openapi (root) that isn't registered — and the Taskfile reads from that
unregistered path (cube-cos-openapi/docs.yaml). On a clean clone,
git submodule update --init won't populate it, so task generateApiDocs
(→ buildLocalBinary / runLocalDevApi) fails. Please keep one submodule path
and make .gitmodules, the gitlink, and the Taskfile agree.

2. Generates fresh every build isn't true for the release artifact

generateApiDocs is wired only into the local-dev tasks. RPM %build and ci.yml
just go build, so they embed the committed api/docs.json, not a regenerated
one. The drift-prevention benefit doesn't apply to the shipped binary.

3. Removing diffApiDocs drops the only drift guard

With the guard gone and regen absent from CI, a stale api/docs.json can ship
silently. Suggest a CI step (with submodules: true):

- run: task generateApiDocs && git diff --exit-code api/docs.json

4. This chore also ships an API-surface change (minor)

The regenerated JSON isn't a pure reformat:

• +2 endpoints (gpuCards, gpuCards/{gpuId})
• +3 schemas (GPUCardStatus, GPUResourceType, GPUSupportResourceType)
• a NodeRole $ref refactor

[raven-pan]

1. Orphan submodule path breaks fresh-clone builds

.gitmodules registers only api/cube-cos-openapi, but there's a second gitlink cube-cos-openapi (root) that isn't registered — and the Taskfile reads from that unregistered path (cube-cos-openapi/docs.yaml). On a clean clone, git submodule update --init won't populate it, so task generateApiDocs (→ buildLocalBinary / runLocalDevApi) fails. Please keep one submodule path and make .gitmodules, the gitlink, and the Taskfile agree.

2. Generates fresh every build isn't true for the release artifact

generateApiDocs is wired only into the local-dev tasks. RPM %build and ci.yml just go build, so they embed the committed api/docs.json, not a regenerated one. The drift-prevention benefit doesn't apply to the shipped binary.

3. Removing diffApiDocs drops the only drift guard

With the guard gone and regen absent from CI, a stale api/docs.json can ship silently. Suggest a CI step (with submodules: true):

- run: task generateApiDocs && git diff --exit-code api/docs.json

4. This chore also ships an API-surface change (minor)

The regenerated JSON isn't a pure reformat:

• +2 endpoints (gpuCards, gpuCards/{gpuId})
• +3 schemas (GPUCardStatus, GPUResourceType, GPUSupportResourceType)
• a NodeRole $ref refactor

Thanks for your review!

These are my solutions,I will:

1. Remove the duplicate cube-cos-openapi submodule from the root folder.
2. Ensure api/docs.json is generated during local development, CI, and the RPM build process.
3. Add the api/docs.json file to .gitignore to prevent drift.
4. This is expected, since 'cube-cos-openapi` should be the single source of truth. I believe a previous manual action caused this inconsistency.

[raven-pan]

1. Orphan submodule path breaks fresh-clone builds

.gitmodules registers only api/cube-cos-openapi, but there's a second gitlink cube-cos-openapi (root) that isn't registered — and the Taskfile reads from that unregistered path (cube-cos-openapi/docs.yaml). On a clean clone, git submodule update --init won't populate it, so task generateApiDocs (→ buildLocalBinary / runLocalDevApi) fails. Please keep one submodule path and make .gitmodules, the gitlink, and the Taskfile agree.

2. Generates fresh every build isn't true for the release artifact

generateApiDocs is wired only into the local-dev tasks. RPM %build and ci.yml just go build, so they embed the committed api/docs.json, not a regenerated one. The drift-prevention benefit doesn't apply to the shipped binary.

3. Removing diffApiDocs drops the only drift guard

With the guard gone and regen absent from CI, a stale api/docs.json can ship silently. Suggest a CI step (with submodules: true):

- run: task generateApiDocs && git diff --exit-code api/docs.json

4. This chore also ships an API-surface change (minor)

The regenerated JSON isn't a pure reformat:

• +2 endpoints (gpuCards, gpuCards/{gpuId})
• +3 schemas (GPUCardStatus, GPUResourceType, GPUSupportResourceType)
• a NodeRole $ref refactor

Thanks for your review!

These are my solutions,I will:

1. Remove the duplicate cube-cos-openapi submodule from the root folder.
2. Ensure api/docs.json is generated during local development, CI, and the RPM build process.
3. Add the api/docs.json file to .gitignore to prevent drift.
4. This is expected, since 'cube-cos-openapi` should be the single source of truth. I believe a previous manual action caused this problem.

Hi @arasHi87

I've already fix issues 1~3, please review again.

Thanks!