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] [--skill] 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

update --skill enchaîne la mise à jour avec la régénération du skill complet, réinstallé automatiquement vers les agents détectés dans le projet (.agents/, .claude/, .opencode/, .vibe/, .github/skills ou .github/copilot-instructions.md). Sans agent détecté, rien n'est installé — utilise build --install --target <cible>.

Développement

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

Metadata

Release files for api-diver 0.4.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.4.0
File Size Uploaded Provenance Actions
api_diver-0.4.0.tar.gz 56.9 kB Without provenance Details for api_diver-0.4.0.tar.gz

Built distribution (wheel)

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

Total release size: 99.7 kB

Release files / api_diver-0.4.0.tar.gz

Download URL api_diver-0.4.0.tar.gz
Size 56.9 kB
Tags Source
SHA-256 checksum
How to use checksums
f1919d1420ede34a55ac31749e57036554504aa2807b0330a54e83ba6e859bed
BLAKE2b-256 checksum
How to use checksums
f2bfc6cfc531990f50623208f998021476a96d4a9dd31262cbae8a9f4a0e5141
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.4.0-py3-none-any.whl

Download URL api_diver-0.4.0-py3-none-any.whl
Size 42.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ca53283c3229684125c9629404ca40558b3ad2e36e64a89a41eb679b90923ad3
BLAKE2b-256 checksum
How to use checksums
fd7e0f266b9fc59a60882ade62448f80bd7eef7d0783e6f2eedab50373d45e08
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.4.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