feat(api-doc): add OpenAPI 3.1.0 + AsyncAPI 3.0.0 + Redoc UI with CI validation

.github/workflows/api-doc.yml

@@ -0,0 +1,44 @@
+name: Validate API Specs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "internal/apidocs/openapi.yaml"
+      - "internal/apidocs/asyncapi.yaml"
+      - ".spectral.yaml"
+      - ".github/workflows/api-doc.yml"
+  pull_request:
+    paths:
+      - "internal/apidocs/openapi.yaml"
+      - "internal/apidocs/asyncapi.yaml"
+      - ".spectral.yaml"
+      - ".github/workflows/api-doc.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  validate-openapi:
+    name: Lint OpenAPI 3.1.0
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Spectral lint
+        run: >
+          npx --yes @stoplight/spectral-cli@6.15.0
+          lint internal/apidocs/openapi.yaml
+          --ruleset .spectral.yaml
+          --fail-severity error
+
+  validate-asyncapi:
+    name: Validate AsyncAPI 3.0.0
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: AsyncAPI validate
+        run: >
+          npx --yes @asyncapi/cli@3.6.0
+          validate internal/apidocs/asyncapi.yaml

.spectral.yaml

@@ -0,0 +1,5 @@
+extends: ["spectral:oas"]
+rules:
+  oas3-schema: error
+  operation-description: warn
+  operation-tags: warn