AetherMint/.github/workflows/openapi.yml at aea53816d2e6088695a361526d5e631e8a468e77 · AetherEdu/AetherMint · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
name: OpenAPI Docs

on:
  push:
    branches: [main, develop]
    paths:
      - 'backend/src/docs/**'
      - 'backend/src/routes/**'
      - 'backend/src/controllers/**'
      - '.github/workflows/openapi.yml'
  pull_request:
    branches: [main, develop]
    paths:
      - 'backend/src/docs/**'
      - 'backend/src/routes/**'
      - 'backend/src/controllers/**'
      - '.github/workflows/openapi.yml'

jobs:
  validate-openapi:
    name: Validate OpenAPI Spec
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install backend dependencies
        run: npm ci -w backend

      - name: Generate OpenAPI spec JSON
        run: |
          cd backend
          npx ts-node -e "
            const spec = require('./src/docs/openapi').openApiSpec;
            const fs = require('fs');
            fs.mkdirSync('dist/docs', { recursive: true });
            fs.writeFileSync('dist/docs/openapi.json', JSON.stringify(spec, null, 2));
            console.log('Spec written to dist/docs/openapi.json');
            const paths = Object.keys(spec.paths || {});
            console.log('Documented paths:', paths.length);
            if (paths.length < 10) {
              console.error('ERROR: fewer than 10 paths documented – check JSDoc annotations');
              process.exit(1);
            }
          "

      - name: Validate spec with swagger-parser
        run: |
          cd backend
          node -e "
            const SwaggerParser = require('@apidevtools/swagger-parser');
            const path = require('path');
            const specPath = path.resolve('dist/docs/openapi.json');
            SwaggerParser.validate(specPath).then(() => {
              console.log('OpenAPI spec is valid.');
            }).catch(err => {
              console.error('OpenAPI validation failed:', err.message);
              process.exit(1);
            });
          "

      - name: Upload spec artifact
        uses: actions/upload-artifact@v4
        with:
          name: openapi-spec
          path: backend/dist/docs/openapi.json
          retention-days: 30

  publish-docs:
    name: Publish Docs to GitHub Pages
    runs-on: ubuntu-latest
    needs: validate-openapi
    # Only publish on pushes to main
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    permissions:
      contents: write
      pages: write
      id-token: write

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install backend dependencies
        run: npm ci -w backend

      - name: Generate OpenAPI spec
        run: |
          cd backend
          npx ts-node -e "
            const spec = require('./src/docs/openapi').openApiSpec;
            const fs = require('fs');
            fs.mkdirSync('dist/docs', { recursive: true });
            fs.writeFileSync('dist/docs/openapi.json', JSON.stringify(spec, null, 2));
          "

      - name: Build Swagger UI static site
        run: |
          mkdir -p docs-site
          # Copy the bundled Swagger UI dist from the installed package
          SWAGGER_DIST=$(node -e "console.log(require('path').dirname(require.resolve('swagger-ui-dist/package.json')))" 2>/dev/null || npx --yes find-up-json swagger-ui-dist)
          cp -r "$(node -e "console.log(require('path').dirname(require.resolve('swagger-ui-dist/swagger-ui.css')))")"/* docs-site/ 2>/dev/null || \
          npx --yes swagger-ui-watcher backend/dist/docs/openapi.json --outDir docs-site || true

          # Write index.html pointing at our spec
          cat > docs-site/index.html << 'HTML'
          <!DOCTYPE html>
          <html lang="en">
          <head>
            <meta charset="UTF-8" />
            <meta name="viewport" content="width=device-width, initial-scale=1.0" />
            <title>AetherMint API Reference</title>
            <link rel="stylesheet" href="swagger-ui.css" />
            <style>
              body { margin: 0; background: #0d1117; }
              .topbar { background-color: #1a1a2e !important; }
            </style>
          </head>
          <body>
            <div id="swagger-ui"></div>
            <script src="swagger-ui-bundle.js"></script>
            <script src="swagger-ui-standalone-preset.js"></script>
            <script>
              SwaggerUIBundle({
                url: './openapi.json',
                dom_id: '#swagger-ui',
                presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
                layout: 'StandaloneLayout',
                docExpansion: 'list',
                filter: true,
                showRequestDuration: true,
              });
            </script>
          </body>
          </html>
          HTML

          # Copy spec into docs-site
          cp backend/dist/docs/openapi.json docs-site/openapi.json

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs-site
          commit_message: 'docs: publish OpenAPI spec [skip ci]'