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)
- Récupère l'URL ; si c'est déjà un swagger.json/openapi.json → spec directe.
- Si c'est une page swagger-ui HTML : extrait les specs référencées
(config
JSON.parseembarquée, tableauxurls,configUrl,data-spec-url, puis fallbacksswagger.json,v1/swagger.json...). - 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é.
- Les multi-domaines sont gérés :
servers[]OpenAPI 3 (avec variables{env}résolues),schemes × host + basePathSwagger 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.