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.2.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.2.0
File Size Uploaded Provenance Actions
api_diver-0.2.0.tar.gz 55.2 kB Without provenance Details for api_diver-0.2.0.tar.gz

Built distribution (wheel)

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

Total release size: 96.9 kB

Release files / api_diver-0.2.0.tar.gz

Download URL api_diver-0.2.0.tar.gz
Size 55.2 kB
Tags Source
SHA-256 checksum
How to use checksums
45bbfa49b7b16d762f4fc39041cc9926a10c8a83143c8ded377c3c33f2e85162
BLAKE2b-256 checksum
How to use checksums
7c16bc3d240b7383a30a27729469b093a62f0946cd2e3034d00be302ffe4ea88
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.2.0-py3-none-any.whl

Download URL api_diver-0.2.0-py3-none-any.whl
Size 41.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
51aabde05d810c465a17763b5038b303b97b2a5494ef818a2d9ad5312b5300ca
BLAKE2b-256 checksum
How to use checksums
8800f424e8cde7164bcc539338c0746be569aefc90b78101cd520dd9e772d812
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.2.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