Skip to main content

api-diver

Cartographie des swaggers/OpenAPI en skills agents. Tu donnes juste une URL (une spec JSON ou une page swagger-ui), api-diver découvre tout seul les specs derrière, les multi-domaines, les routes, leurs paramètres et payloads — puis génère un skill au format standard Agent Skills installable pour OpenCode, Mistral Vibe, Claude Code, Codex, GitHub Copilot (et tout agent compatible via .agents/).

Installation

uv tool install .        # ou : pipx install .

Démarrage rapide

# 1. créer une base de connaissance (une seule fois)
api-diver init apis-perso
cd apis-perso

# 2. ajouter des URLs de swagger, quand tu veux
api-diver add https://vnext.sosoxygene.com/api-stock/swagger/index.html
api-diver add https://petstore.swagger.io/v2/swagger.json --name petstore

# 3. mettre à jour les routes (une commande)
api-diver update            # toutes les APIs
api-diver update api-stock  # une seule

# 4. générer / installer le skill
api-diver build --install                  # .agents/skills/ (OpenCode + Vibe + Codex)
api-diver build --target claude --install  # .claude/skills/ (Claude Code)
api-diver build --target copilot --install # .github/skills/ (Copilot)
api-diver build --target vibe --install --global

Ce que fait add (découverte automatique)

  1. Récupère l'URL ; si c'est déjà un swagger.json/openapi.json → spec directe.
  2. Si c'est une page swagger-ui HTML : extrait les specs référencées (config JSON.parse embarquée, tableaux urls, configUrl, data-spec-url, puis fallbacks swagger.json, v1/swagger.json...).
  3. Chaque spec découverte est crawlée (le cas Swashbuckle multi-docs — « Agency Tanks », « Articles »... — devient une API avec un groupe par spec), puis tout est fusionné.
  4. Les multi-domaines sont gérés : servers[] OpenAPI 3 (avec variables {env} résolues), schemes × host + basePath Swagger 2.

Workspace (base de connaissance)

apis-perso/
├── apidiver.json           # registry : sources, URLs des specs, refs d'auth
└── specs/<api>/
    ├── raw/*.json          # specs brutes téléchargées (+ .prev : historique)
    └── normalized.json     # modèle fusionné (+ .prev)
  • api-diver list / info <api> / diff <api> : explorer le workspace.
  • api-diver remove <api> : retirer une API.

Skill généré

<skill>/
├── SKILL.md                # index + guide de navigation (progressive disclosure)
└── apis/<api>/
    ├── overview.md         # domaines (base URLs), groupes, auth, tags
    └── routes/
        ├── _index.md       # METHOD chemin → fichier
        └── <tag>.md        # fiches : params, payload + exemple JSON,
                            # réponses détaillées, exemple curl

Les exemples curl utilisent des placeholders $NOM_API_TOKEN-style : aucun secret n'est jamais écrit dans le workspace ni le skill.

Cibles d'installation (build --target)

Cible Dossier projet (--install) Dossier global (--install --global) Agent
agents (défaut) .agents/skills/ ~/.agents/skills/ OpenCode, Mistral Vibe, tout agent compatible
opencode .opencode/skills/ ~/.config/opencode/skills/ OpenCode
vibe .vibe/skills/ ~/.vibe/skills/ Mistral Vibe
claude .claude/skills/ ~/.claude/skills/ Claude Code
codex .agents/skills/ ~/.agents/skills/ Codex (≥ 0.95 : lit le dossier standard .agents)
copilot .github/skills/ ~/.copilot/skills/ GitHub Copilot (VS Code, CLI, coding agent)

Authentification des sources protégées

# valeur lue dans l'environnement à chaque fetch (recommandé, persisté en ref)
api-diver add https://.../swagger.json --header "Authorization: {\$MY_TOKEN}"

# ou globalement
export API_DIVER_HEADERS='{"X-Api-Key": "{$MY_KEY}"}'

Une valeur brute (--header "Authorization: Bearer xyz") sert au fetch du moment et n'est jamais stockée.

Commandes

Commande Rôle
init [path] Créer le workspace
add <url> [--name n] Crawler + ajouter une source (découverte auto)
update [name] Re-crawler et rafraîchir les routes (+ résumé diff)
list / info <name> Explorer le workspace
diff <name> Changements de routes depuis la version précédente
remove <name> Supprimer une API
build [--target agents|opencode|vibe|claude|codex|copilot] [--install] [--global] Générer/installer le skill

Développement

uv venv && uv pip install -e . pytest
uv run pytest

Metadata

Release files for api-diver 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for api-diver 0.3.0
File Size Uploaded Provenance Actions
api_diver-0.3.0.tar.gz 55.8 kB Without provenance Details for api_diver-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for api-diver 0.3.0
File Interpreter ABI Platform Actions
api_diver-0.3.0-py3-none-any.whl Python 3 none any Details for api_diver-0.3.0-py3-none-any.whl

Total release size: 97.8 kB

Release files / api_diver-0.3.0.tar.gz

Download URL api_diver-0.3.0.tar.gz
Size 55.8 kB
Tags Source
SHA-256 checksum
How to use checksums
90d98deb4cef5c25ec20110c41ff9f4ee1778d8c43f4b69eeec780f300757f18
BLAKE2b-256 checksum
How to use checksums
02cf819dc59001bc9f937560f2104ee183f8ac9b0d439d5247c29e78223f5f7a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / api_diver-0.3.0-py3-none-any.whl

Download URL api_diver-0.3.0-py3-none-any.whl
Size 42.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9a1bddcb0a51aaaceb99f0aa2811520562c911f4bde313be4265a48185d95dc3
BLAKE2b-256 checksum
How to use checksums
45a7d467e2f238d8311bec2087c6ecf9293837d9dd81068db8edd22948b36f68
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for api-diver 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page