Spec: add generated JSON version and CI check

.github/workflows/spec.yml

@@ -0,0 +1,46 @@
+name: Spec
+
+on:
+  pull_request:
+  push:
+    branches: [trunk]
+
+jobs:
+  generate:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    env:
+      # The workflow token can only push to branches in this repository, not to forks.
+      CAN_PUSH: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Check out the PR branch itself (not the merge commit) so spec.json can be pushed back to it.
+          repository: ${{ github.event.pull_request.head.repo.full_name || github.repository }}
+          ref: ${{ github.head_ref || github.ref_name }}
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - name: Lint spec.yml
+        run: npx -y @redocly/cli@2.55.0 lint spec.yml
+      - name: Regenerate spec.json
+        run: npx -y @redocly/cli@2.55.0 bundle spec.yml -o spec.json
+      - name: Commit spec.json
+        if: env.CAN_PUSH == 'true'
+        run: |
+          if git diff --quiet spec.json; then
+            echo "spec.json is already up to date."
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git commit -m "Regenerate spec.json from spec.yml" spec.json
+          git push
+      - name: Check spec.json is up to date
+        if: env.CAN_PUSH != 'true'
+        run: |
+          git diff --exit-code spec.json || {
+            echo "::error file=spec.json::spec.json is out of date. Run: npx @redocly/cli@2.55.0 bundle spec.yml -o spec.json"
+            exit 1
+          }

README.md

@@ -6,6 +6,16 @@ We have created an OpenAPI spec.yml file adhering to the OpenAPI v3.0.3 specific
 
 For example, you can import the specification into [SwaggerHub](https://github.com/Automattic/akismet-api/wiki/Using-the-Akismet-API-spec-with-SwaggerHub) or [Postman](https://www.postman.com/) to experiment with the API. You can also generate code to work with the API automatically - we recommend [OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator) for this.
 
+## JSON version
+
+A JSON version of the spec is available in [`spec.json`](spec.json). It is generated from `spec.yml`, so only edit `spec.yml`.
+
+On every pull request, CI lints `spec.yml`, regenerates `spec.json`, and commits it to the PR branch if it changed. Pull requests from forks can't be pushed to, so there CI fails if `spec.json` is out of date and you'll need to regenerate it yourself:
+
+```sh
+npx @redocly/cli@2.55.0 bundle spec.yml -o spec.json
+```
+
 ## Guides
 
 * [Using the Akismet API spec with SwaggerHub](https://github.com/Automattic/akismet-api/wiki/Using-the-Akismet-API-spec-with-SwaggerHub)

redocly.yaml

@@ -0,0 +1,9 @@
+extends:
+  - recommended
+
+rules:
+  # The API key is sent as a form/query parameter rather than via an OpenAPI security scheme.
+  security-defined: off
+  # Akismet signals errors with 200 responses and plain-text bodies (e.g. "invalid").
+  operation-4xx-response: off
+  info-license: off