Skip to content

feat: migrate to unified OpenAPI v4 specification #227

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jose-torquato wants to merge 4 commits into
base: main
Choose a base branch
from
Open

feat: migrate to unified OpenAPI v4 specification #227

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f7dd569
feat: add openapi.yaml v4 specification
jose-torquato Jan 29, 2026
37f3756
chore: remove legacy v3 API specifications
jose-torquato Jan 29, 2026
55d7900
feat: update spectral rules from v4-openapi
jose-torquato Jan 29, 2026
f5122c0
feat: update workflows and README for v4 structure
jose-torquato Jan 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 13 additions & 49 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,64 +1,28 @@

name: CI

on:
push:
branches: [ main ]
branches: [main]
pull_request:
branches: [ main ]

# Allows you to run this workflow manually from the Actions tab
branches: [main]
workflow_dispatch:

jobs:
test_job:
validate:
name: Validate OpenAPI
runs-on: ubuntu-latest
container:
image: ubuntu:22.04
steps:
- name: Setup Env
run: apt-get update && apt-get install -y git npm

- uses: actions/setup-node@v3
with:
node-version: 14

- name: Setting GIT
run: git config --global url."https://${{ secrets.GLOBAL_TOKEN }}:x-oauth-basic@github.com/aziontech".insteadOf "https://github.com/aziontech"

steps:
- name: Checkout code
uses: actions/checkout@v3
with:
fetch-depth: 0

- name: Git config
run: git config --global --add safe.directory /__w/azionapi-openapi/azionapi-openapi
shell: bash
uses: actions/checkout@v4

- name: install openapi-linter
run: npm i -g @superfaceai/openapi-linter

#get all .yaml files which were added/modified
- name: Get changed files
id: changed-files
uses: tj-actions/changed-files@v35
- name: Setup Node.js
uses: actions/setup-node@v4
with:
files: |
**/*.yaml
files_ignore: |
spectral/.spectral*.yaml

- name: Run linter for changed files
run: |
for file in ${{ steps.changed-files.outputs.all_changed_files }}; do
oal lint $file -f yaml
done
node-version: '20'

- name: install redocly-cli
run: npm i -g @redocly/cli@1.0.0-beta.129
- name: Install Redocly CLI
run: npm install -g @redocly/cli

- name: Run linter for changed files
run: |
for file in ${{ steps.changed-files.outputs.all_changed_files }}; do
redocly lint $file
done
- name: Validate OpenAPI v4
run: redocly lint openapi.yaml
Comment on lines +12 to +28

Check warning

Code scanning / CodeQL

Workflow does not contain permissions Medium

Actions job or workflow does not limit the permissions of the GITHUB_TOKEN. Consider setting an explicit permissions block, using the following as a minimal starting point: {contents: read}

Copilot Autofix

AI 13 days ago

In general, you fix this by explicitly specifying permissions for the workflow or for individual jobs, granting only what is actually required. For this CI workflow, the job only reads repository contents, so contents: read at the workflow or job level is sufficient.

The best minimal fix, without changing functionality, is to add a top-level permissions: block right after the workflow name: declaration (around line 1–2) in .github/workflows/ci.yml. This block should set contents: read, which is enough for actions/checkout to work and for the linter to access files. No imports or additional methods are required because this is purely a YAML configuration change.

Suggested changeset 1
.github/workflows/ci.yml

Autofix patch

Autofix patch
Run the following command in your local git repository to apply this patch
cat << 'EOF' | git apply
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -1,4 +1,6 @@
 name: CI
+permissions:
+  contents: read
 
 on:
   push:
EOF
@@ -1,4 +1,6 @@
name: CI
permissions:
contents: read

on:
push:
Copilot is powered by AI and may make mistakes. Always verify output.
74 changes: 15 additions & 59 deletions .github/workflows/linters.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,71 +3,27 @@
on:
pull_request:
branches:
- main
- main
push:
branches:
- main

jobs:
spectral:
spectral-v4:
name: Lint OpenAPI v4
runs-on: ubuntu-latest
container:
image: node:14-alpine3.12

steps:
- name: Checkout code
uses: actions/checkout@v3

- name: Install Spectral
run: npm install @stoplight/spectral-cli

- name: Run Spectral Lint on Credentials API
run: npx spectral lint --verbose --ruleset spectral/.spectral-credentials.yaml credentials.yaml --display-only-failures || exit 1

- name: Run Spectral Lint on Data Streaming API
run: npx spectral lint --verbose --ruleset spectral/.spectral-datastreaming.yaml data_streaming.yaml --display-only-failures || exit 1

- name: Run Spectral Lint on Digital Certificates API
run: npx spectral lint --verbose --ruleset spectral/.spectral-digital_certificates.yaml digital_certificates.yaml --display-only-failures || exit 1

- name: Run Spectral Lint on Domains API
run: npx spectral lint --verbose --ruleset spectral/.spectral-domains.yaml domains.yaml --display-only-failures || exit 1

- name: Run Spectral Lint on Edge Applications API
run: npx spectral lint --verbose --ruleset spectral/.spectral-edgeapplications.yaml edgeapplications.yaml --display-only-failures || exit 1

- name: Run Spectral Lint on Edge Firewall API
run: npx spectral lint --verbose --ruleset spectral/.spectral-edgefirewall.yaml edgefirewall.yaml --display-only-failures || exit 1

- name: Run Spectral Lint on Edge Functions API
run: npx spectral lint --verbose --ruleset spectral/.spectral-edgefunctions.yaml edgefunctions.yaml --display-only-failures || exit 1
uses: actions/checkout@v4

- name: Run Spectral Lint on Edge Functions Instance Edge Firewall API
run: npx spectral lint --verbose --ruleset spectral/.spectral-edgefuncinstedgefirewall.yaml edgefunctionsinstance_edgefirewall.yaml --display-only-failures || exit 1
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'

- name: Run Spectral Lint on Edge Node API
run: npx spectral lint --verbose --ruleset spectral/.spectral-edgenode.yaml edgenode.yaml --display-only-failures || exit 1

- name: Run Spectral Lint on IAM API API
run: npx spectral lint --verbose --ruleset spectral/.spectral-iam.yaml iam.yml --display-only-failures || exit 1

- name: Run Spectral Lint on Intelligent DNS API
run: npx spectral lint --verbose --ruleset spectral/.spectral-idns.yaml idns.yaml --display-only-failures || exit 1

- name: Run Spectral Lint on Network List API
run: npx spectral lint --verbose --ruleset spectral/.spectral-networklist.yaml networklist.yaml --display-only-failures || exit 1

- name: Run Spectral Lint on Personal Tokens API
run: npx spectral lint --verbose --ruleset spectral/.spectral-personaltokens.yaml personal_tokens.yaml --display-only-failures || exit 1

- name: Run Spectral Lint on Realtime Purge API
run: npx spectral lint --verbose --ruleset spectral/.spectral-realtimepurge.yaml realtimepurge.yaml --display-only-failures || exit 1

- name: Run Spectral Lint on Services API
run: npx spectral lint --verbose --ruleset spectral/.spectral-services.yaml services.yaml --display-only-failures || exit 1

- name: Run Spectral Lint on Storage API
run: npx spectral lint --verbose --ruleset spectral/.spectral-storage.yaml storage.yaml --display-only-failures || exit 1

- name: Run Spectral Lint on Variables API
run: npx spectral lint --verbose --ruleset spectral/.spectral-variables.yaml variables.yaml --display-only-failures || exit 1
- name: Install Spectral
run: npm install -g @stoplight/spectral-cli

- name: Run Spectral Lint on WAF API
run: npx spectral lint --verbose --ruleset spectral/.spectral-waf.yaml waf.yaml --display-only-failures || exit 1
- name: Run Spectral Lint on OpenAPI v4
run: spectral lint openapi.yaml --ruleset spectral/spectral.yaml --verbose
Comment on lines +13 to +29

Check warning

Code scanning / CodeQL

Workflow does not contain permissions Medium

Actions job or workflow does not limit the permissions of the GITHUB_TOKEN. Consider setting an explicit permissions block, using the following as a minimal starting point: {contents: read}

Copilot Autofix

AI 13 days ago

In general, the fix is to explicitly declare a permissions block to limit the default GITHUB_TOKEN permissions to the minimum needed. For this workflow, the steps only read repository contents and do not write anywhere, so contents: read at the workflow or job level is sufficient.

The best way to fix this without changing functionality is to add a top-level permissions block right after the name: (before on:) in .github/workflows/linters.yml. This way, the restriction applies to all jobs in the workflow (currently just spectral-v4). The exact change: insert

permissions:
  contents: read

between existing lines 2 and 3. No imports or new methods are needed because this is only a YAML configuration change.

Suggested changeset 1
.github/workflows/linters.yml

Autofix patch

Autofix patch
Run the following command in your local git repository to apply this patch
cat << 'EOF' | git apply
diff --git a/.github/workflows/linters.yml b/.github/workflows/linters.yml
--- a/.github/workflows/linters.yml
+++ b/.github/workflows/linters.yml
@@ -1,5 +1,8 @@
 name: OpenAPI Spectral Linter
 
+permissions:
+  contents: read
+
 on:
   pull_request:
     branches:
EOF
@@ -1,5 +1,8 @@
name: OpenAPI Spectral Linter

permissions:
contents: read

on:
pull_request:
branches:
Copilot is powered by AI and may make mistakes. Always verify output.
66 changes: 66 additions & 0 deletions .github/workflows/sync-v4.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
name: Sync from azionapi-v4-openapi

on:
# Triggered by repository dispatch from azionapi-v4-openapi
repository_dispatch:
types: [sync-openapi-v4]

# Manual trigger
workflow_dispatch:
inputs:
source_ref:
description: 'Branch or tag from azionapi-v4-openapi to sync from'
required: false
default: 'main'

jobs:
sync:
name: Sync OpenAPI v4
runs-on: ubuntu-latest

steps:
- name: Checkout azionapi-openapi
uses: actions/checkout@v4
with:
token: ${{ secrets.GLOBAL_TOKEN }}
fetch-depth: 0

- name: Checkout azionapi-v4-openapi
uses: actions/checkout@v4
with:
repository: aziontech/azionapi-v4-openapi
ref: ${{ github.event.inputs.source_ref || 'main' }}
path: v4-source
token: ${{ secrets.GLOBAL_TOKEN }}

- name: Sync openapi.yaml
run: |
cp v4-source/openapi.yaml openapi.yaml
echo "Synced openapi.yaml from azionapi-v4-openapi"

- name: Sync spectral rules
run: |
rm -rf spectral
cp -r v4-source/spectral spectral
echo "Synced spectral rules from azionapi-v4-openapi"

- name: Cleanup
run: rm -rf v4-source

- name: Check for changes
id: changes
run: |
if git diff --quiet; then
echo "has_changes=false" >> $GITHUB_OUTPUT
else
echo "has_changes=true" >> $GITHUB_OUTPUT
fi

- name: Commit and push changes
if: steps.changes.outputs.has_changes == 'true'
run: |
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
git add openapi.yaml spectral/
git commit -m "chore: sync openapi.yaml and spectral from azionapi-v4-openapi"
git push
Comment on lines +18 to +66

Check warning

Code scanning / CodeQL

Workflow does not contain permissions Medium

Actions job or workflow does not limit the permissions of the GITHUB_TOKEN. Consider setting an explicit permissions block, using the following as a minimal starting point: {contents: read}

Copilot Autofix

AI 13 days ago

To fix the problem, explicitly declare a permissions block so the GITHUB_TOKEN used in this workflow has only the privileges required. This can be done at the workflow root (applies to all jobs) or at the job level; here we will add it to the sync job, which is the flagged one.

The job performs checkouts and then commits and pushes back to the same repository. Committing and pushing require write access to repository contents, so we should grant contents: write and nothing else. No additional scopes (issues, pull‑requests, etc.) are needed. The smallest, non‑breaking change is to add a permissions: stanza under jobs.sync alongside runs-on.

Concretely:

  • Edit .github/workflows/sync-v4.yml.
  • Under jobs:, in the sync: job, add:
    permissions:
      contents: write
  • Keep indentation aligned with runs-on: (two spaces more than sync:) so the YAML remains valid.
  • No imports, methods, or additional definitions are needed; this is a pure configuration change.
Suggested changeset 1
.github/workflows/sync-v4.yml

Autofix patch

Autofix patch
Run the following command in your local git repository to apply this patch
cat << 'EOF' | git apply
diff --git a/.github/workflows/sync-v4.yml b/.github/workflows/sync-v4.yml
--- a/.github/workflows/sync-v4.yml
+++ b/.github/workflows/sync-v4.yml
@@ -17,6 +17,8 @@
   sync:
     name: Sync OpenAPI v4
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
 
     steps:
       - name: Checkout azionapi-openapi
EOF
@@ -17,6 +17,8 @@
sync:
name: Sync OpenAPI v4
runs-on: ubuntu-latest
permissions:
contents: write

steps:
- name: Checkout azionapi-openapi
Copilot is powered by AI and may make mistakes. Always verify output.
39 changes: 28 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,17 +3,34 @@

OpenAPI 3.0 specification for Azion APIs.

|YAML|DESCRIPTION|
|---|---|
|`credentials.yaml`|Credentials API, part of the Orchestration Architecture.|
|`domains.yaml`|Domains API enables you to retrieve, create, remove or update Domains used by Edge Applications.|
|`edgeapplications.yaml`|Edge Applications allows you to check, remove and/or update your existing settings, as well as creating new ones.|
|`edgefunctions.yaml`|Edge Functions API.|
|`edgenode.yaml`|Edge Node API, part of the Orchestration Architecture.|
|`idns.yaml`|Intelligent DNS API.|
|`realtimepurge.yaml`|Real-Time Purge API enables you to purge a cache entry before its TTL for Edge Caching or L2 Caching|
|`services.yaml`|Edge Services API, part of the Orchestration Architecture.|
|`waf.yaml`|WAF API -- WAF self-calibration enables you to create allowed rules that are meaningful to your application.|
## 📄 OpenAPI Files

### API v4 (Current)
- **[openapi.yaml](openapi.yaml)** - Complete Azion API v4 specification

### API v3 (Legacy)
Legacy API specifications are available in the `v3/` directory for backward compatibility.

## 🚀 Quick Start

```bash
# View with Swagger UI
npx @redocly/cli preview-docs openapi.yaml

# Validate with Spectral
npx @stoplight/spectral-cli lint openapi.yaml --ruleset spectral/spectral.yaml

# Generate client SDKs
openapi-generator-cli generate -i openapi.yaml -g python -o ./client
```

## 📚 Documentation

- **[Spectral Validation Rules](spectral/README.md)** - Comprehensive guide to all custom Spectral linting rules

## 🔄 Synchronization

The `openapi.yaml` file is automatically synchronized from [azionapi-v4-openapi](https://github.com/aziontech/azionapi-v4-openapi) when changes are merged to the main branch.

## License

Expand Down
Loading
Loading