mitmproxy2swagger

mitmproxy2swagger

vidéo.mp4

Un outil pour convertir automatiquement les captures Mitmproxy aux spécifications OpenAPI 3.0. Cela signifie que vous pouvez automatiquement rétrograder les API REST ingénieurs en exécutant simplement les applications et en capturant le trafic.

---

? NOUVEAU!

Ajout de la prise en charge du traitement HAR exporté du navigateur Devtools. Voir usage - Har pour plus de détails.

---

Installation

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 .

Ensuite, clonez le dépôt et exécutez mitmproxy2swagger selon les exemples ci-dessous.

Usage

Mitmproxy

Pour créer une spécification en inspectant le trafic HTTP, vous devrez:

1. Capturez le trafic à l'aide de l'outil Mitmproxy. Je recommande personnellement d'utiliser MITMWEB, qui est 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 pour utiliser le proxy exposé par le proxy MITM, veuillez consulter la documentation Mitmproxy pour plus d'informations.

2. Enregistrez le trafic dans un fichier de flux.

   Dans MITMWEB, vous pouvez le faire en utilisant le menu "Fichier" et en sélectionnant "Enregistrer":

   

3. 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 étendu 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énieur. Vous devrez l'obtenir en observant les demandes faites dans Mitmproxy.

   Par exemple, si une application a fait des demandes comme celles-ci:

    https://api.example.com/v1/login
   https://api.example.com/v1/users/2
   https://api.example.com/v1/users/2/profile

   Le préfixe probable est https://api.example.com/v1 .

4. L'exécution de la première passe aurait dû créer une section dans le fichier de schéma comme ceci:

    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.

5. 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). Il ramassera les lignes éditées et générera des descriptions de points de terminaison.

   Veuillez noter que Mitmproxy2Swagger ne remplacera 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.

   Passing --examples ajoutera des exemples de données aux demandes et aux réponses. Prenez prudence lorsque vous utilisez cette option, car elle peut ajouter des données sensibles (jetons, mots de passe, informations personnelles, etc.) au schéma. Passage --headers ajouteront des données en en-têtes aux demandes et aux réponses. Prenez prudence lorsque vous utilisez cette option, car elle peut ajouter des données sensibles (jetons, mots de passe, informations personnelles, etc.) au schéma.

Har

1. Capturez et exportez le trafic du navigateur Devtools.

   Dans le navigateur Devtools, accédez à l'onglet réseau et cliquez sur le bouton "Exporter HAR".

   

2. Continuez de la même manière que vous feriez avec le vidage mitmproxy. mitmproxy2swagger détectera automatiquement le fichier HAR et le traitera.

Exemple de sortie

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é ici.

Développement et contribution

Ce projet utilise:

• Poésie pour la gestion des dépendances
• Pré-engagement pour le formatage et la libellur
• Pytest pour les tests unitaires

Pour installer les dépendances:

poetry install

Exécuter des liners:

pre-commit run --all-files

Installer des crochets pré-engageants:

pre-commit install

Exécutez des tests:

poetry run pytest

Exécutez des tests avec la couverture:

poetry run pytest --cov=mitmproxy2swagger

Licence

Mit