alufers/mitmproxy2swaggerRétro-ingénierie automatique des API REST en capturant le trafic
https://user-images.githubusercontent.com/5400940/168086818-c48f60ab-3f95-42eb-b435-c8b1a6326b81.mp4
Un outil pour convertir automatiquement les captures mitmproxy en spécifications OpenAPI 3.0. Cela signifie que vous pouvez rétro-ingénierer automatiquement des API REST simplement en exécutant les applications et en capturant le trafic.
🆕 NOUVEAU !
Ajout de la prise en charge du traitement des fichiers HAR exportés depuis les DevTools du navigateur. Voir Utilisation - HAR pour plus de détails.
Vous aurez d'abord besoin de python3 et pip3.
$ pip install mitmproxy2swagger
# ... or ...
$ pip3 install mitmproxy2swagger
# ... or ...
$ git clone [email protected]:alufers/mitmproxy2swagger.git
$ cd mitmproxy2swagger
$ docker build -t mitmproxy2swagger .
Clonez ensuite le dépôt et exécutez mitmproxy2swagger comme dans les exemples ci-dessous.
Pour créer une spécification en inspectant le trafic HTTP, vous devez :
Capturez le trafic en utilisant l'outil mitmproxy. Je recommande personnellement d'utiliser mitmweb, une interface web intégrée à mitmproxy.
$ mitmweb
Web server listening at http://127.0.0.1:8081/
Proxy server listening at http://*:9999
...
IMPORTANT
Pour configurer votre client afin d'utiliser le proxy exposé par mitmproxy, veuillez consulter la documentation mitmproxy pour plus d'informations.
Enregistrez le trafic dans un fichier flow.
Dans mitmweb, vous pouvez le faire en utilisant le menu "File" et en sélectionnant "Save" :
Exécutez la première passe de mitmproxy2swagger :
$ mitmproxy2swagger -i <path_to_mitmptoxy_flow> -o <path_to_output_schema> -p <api_prefix>
# ... or ...
$ docker run -it -v $PWD:/app mitmproxy2swagger mitmproxy2swagger -i <path_to_mitmptoxy_flow> -o <path_to_output_schema> -p <api_prefix>
Veuillez noter que vous pouvez utiliser un schéma existant, auquel cas le schéma existant sera complété avec les nouvelles données. Vous pouvez également l'exécuter plusieurs fois avec différentes captures de flux, les données capturées seront fusionnées en toute sécurité.
<api_prefix> est l'URL de base de l'API que vous souhaitez rétro-ingénierer. Vous devrez l'obtenir en observant les requêtes effectuées dans mitmproxy.
Par exemple, si une application a effectué des requêtes comme celles-ci :
https://api.example.com/v1/login
https://api.example.com/v1/users/2
https://api.example.com/v1/users/2/profile
Capturez et exportez le trafic depuis les DevTools du navigateur.
Dans les DevTools du navigateur, allez dans l'onglet Network et cliquez sur le bouton 'Export HAR'.
Continuez de la même manière qu'avec le dump mitmproxy. mitmproxy2swagger détectera automatiquement le fichier HAR et le traitera.
Voir les exemples. Vous y trouverez un schéma généré et un fichier HTML avec la documentation générée (via redoc-cli).
Voir le fichier HTML généré.
Ce projet utilise :
Pour installer les dépendances :
uv sync
Exécuter les linters :
uv run prek run --all-files
Installer les hooks prek :
uv run prek install
Exécuter les tests :
uv run pytest
Exécuter les tests avec couverture :
uv run pytest --cov=mitmproxy2swagger
MIT
Le préfixe probable est https://api.example.com/v1.
L'exécution de la première passe devrait avoir créé une section dans le fichier de schéma comme celle-ci :
x-path-templates:
# Remove the ignore: prefix to generate an endpoint with its URL
# Lines that are closer to the top take precedence, the matching is greedy
- ignore:/addresses
- ignore:/basket
- ignore:/basket/add
- ignore:/basket/checkouts
- ignore:/basket/coupons/attach/{id}
- ignore:/basket/coupons/attach/104754
Vous devez modifier le fichier de schéma avec un éditeur de texte et supprimer le préfixe ignore: des chemins que vous souhaitez générer. Vous pouvez également ajuster les paramètres apparaissant dans les chemins.
Exécutez la deuxième passe de mitmproxy2swagger :
$ mitmproxy2swagger -i <path_to_mitmptoxy_flow> -o <path_to_output_schema> -p <api_prefix> [--examples]
# ... or ...
$ docker run -it -v $PWD:/app mitmproxy2swagger mitmproxy2swagger -i <path_to_mitmptoxy_flow> -o <path_to_output_schema> -p <api_prefix> [--examples]
Exécutez la commande une deuxième fois (avec le même fichier de schéma). Elle prendra en compte les lignes modifiées et générera les descriptions des points de terminaison.
Veuillez noter que mitmproxy2swagger n'écrasera pas les descriptions de points de terminaison existantes ; si vous souhaitez les écraser, vous pouvez les supprimer avant d'exécuter la deuxième passe.
Le passage de --examples ajoutera des exemples de données aux requêtes et réponses. Soyez prudent lorsque vous utilisez cette option, car elle peut ajouter des données sensibles (jetons, mots de passe, informations personnelles, etc.) au schéma.
Le passage de --headers ajoutera les données d'en-tête aux requêtes et réponses. Soyez prudent lorsque vous utilisez cette option, car elle peut ajouter des données sensibles (jetons, mots de passe, informations personnelles, etc.) au schéma.