ci: export OpenAPI spec as CI artifact (#40)

Backend/package.json

@@ -20,7 +20,8 @@
     "test:e2e": "jest --config ./test/jest-e2e.json",
     "migration:run": "ts-node -r tsconfig-paths/register ./node_modules/typeorm/cli.js -d src/database/data-source.ts migration:run",
     "migration:revert": "ts-node -r tsconfig-paths/register ./node_modules/typeorm/cli.js -d src/database/data-source.ts migration:revert",
-    "migration:generate": "ts-node -r tsconfig-paths/register ./node_modules/typeorm/cli.js -d src/database/data-source.ts migration:generate"
+    "migration:generate": "ts-node -r tsconfig-paths/register ./node_modules/typeorm/cli.js -d src/database/data-source.ts migration:generate",
+    "export-spec": "ts-node -r tsconfig-paths/register src/export-spec.ts"
   },
   "lint-staged": {
     "*.ts": "eslint --fix"
@@ -40,6 +41,7 @@
     "csrf": "^3.1.0",
     "ethers": "^6.15.0",
     "ioredis": "^5.11.1",
+    "js-yaml": "^5.0.0",
     "pg": "^8.13.3",
     "reflect-metadata": "^0.2.2",
     "rxjs": "^7.8.1",
@@ -57,6 +59,7 @@
     "@types/express": "^5.0.0",
     "@types/geojson": "^7946.0.16",
     "@types/jest": "^29.5.14",
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.10.7",
     "@types/sanitize-html": "^2.13.0",
     "@types/supertest": "^6.0.2",

Backend/src/export-spec.ts

@@ -0,0 +1,35 @@
+import { NestFactory } from '@nestjs/core';
+import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
+import { writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { dump } from 'js-yaml';
+import { AppModule } from './app.module';
+
+const docsDir = join(__dirname, '..', '..', 'infrastructure', 'docs');
+
+(async () => {
+  try {
+    const app = await NestFactory.create(AppModule, { logger: false });
+    await app.init();
+
+    const swaggerConfig = new DocumentBuilder()
+      .setTitle('Gist API')
+      .setDescription('Anonymous hyperlocal messaging on Stellar')
+      .setVersion('0.1.0')
+      .build();
+
+    const document = SwaggerModule.createDocument(app, swaggerConfig);
+
+    mkdirSync(docsDir, { recursive: true });
+    writeFileSync(
+      join(docsDir, 'openapi.json'),
+      JSON.stringify(document, null, 2),
+    );
+    writeFileSync(join(docsDir, 'openapi.yaml'), dump(document));
+
+    await app.close();
+  } catch (error) {
+    console.error(error);
+    process.exit(1);
+  }
+})();

infrastructure/ci/docs-generation.yml

@@ -19,17 +19,56 @@ jobs:
   generate-api-docs:
     name: API Docs
     runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:15
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: vertexchain_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
     steps:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: Backend/package-lock.json
+
+      - name: Install Backend dependencies
+        run: cd Backend && npm ci
+
       - name: Generate OpenAPI and static docs
+        env:
+          DATABASE_HOST: localhost
+          DATABASE_PORT: 5432
+          DATABASE_USER: postgres
+          DATABASE_PASSWORD: postgres
+          DATABASE_NAME: vertexchain_test
         run: |
           version="${{ github.event.release.tag_name }}"
           if [ -z "$version" ]; then version="$(date +%Y.%m.%d)"; fi
           bash infrastructure/scripts/generate-api-docs.sh "$version"
 
+      - name: Upload OpenAPI spec artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: openapi-spec
+          path: |
+            infrastructure/docs/openapi.json
+            infrastructure/docs/openapi.yaml
+          if-no-files-found: error
+
       - name: Commit API docs
         run: |
           git config user.name "github-actions[bot]"

infrastructure/scripts/generate-api-docs.sh

@@ -17,18 +17,16 @@ mkdir -p "$(dirname "${spec_output}")" "${site_output}" "$(dirname "${version_fi
 version="${1:-$(date +%Y.%m.%d)}"
 echo "${version}" > "${version_file}"
 
-cat > "${spec_output}" <<EOF
-{
-  "openapi": "3.0.0",
-  "info": {
-    "title": "VertexChain API",
-    "version": "${version}"
-  },
-  "paths": {}
-}
-EOF
-
-cat > "${site_output}/index.html" <<EOF
+# Export real OpenAPI spec from NestJS app
+cd Backend
+npm run export-spec
+cd ..
+
+# Copy YAML output alongside JSON
+cp infrastructure/docs/openapi.yaml "$(dirname "${spec_output}")/openapi.yaml"
+
+# Generate minimal static site
+cat > "${site_output}/index.html" <<HTMLEOF
 <!doctype html>
 <html>
   <head><meta charset="utf-8"><title>VertexChain API Docs</title></head>
@@ -43,6 +41,6 @@ cat > "${site_output}/index.html" <<EOF
     </script>
   </body>
 </html>
-EOF
+HTMLEOF
 
 echo "Generated API docs for version ${version}"