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 utilisable par OpenCode, Mistral Vibe (et tout agent compatible : Claude Code, ZCode... 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)
api-diver build --target opencode --install
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.

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] [--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.1.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.1.0
File Size Uploaded Provenance Actions
api_diver-0.1.0.tar.gz 55.8 kB Without provenance Details for api_diver-0.1.0.tar.gz

Built distribution (wheel)

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

Total release size: 96.2 kB

Release files / api_diver-0.1.0.tar.gz

Download URL api_diver-0.1.0.tar.gz
Size 55.8 kB
Tags Source
SHA-256 checksum
How to use checksums
5341c4faeaf879835d862f458d39a0cab1d521823112dfb3849f4c6aba2d5480
BLAKE2b-256 checksum
How to use checksums
92864cf6645697c6fe4f371966e016c5978f3f30414e46431f0975ad74e4ab83
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.1.0-py3-none-any.whl

Download URL api_diver-0.1.0-py3-none-any.whl
Size 40.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
dae216792735bd26f626fb21e94df473283605db8b775a0e11797520f92551ab
BLAKE2b-256 checksum
How to use checksums
da28c116af10c5e4f69d5b6e596f782af6dfab4fb0764be58ff2f7d5f5925c78
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.1.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