diff --git a/README.md b/README.md index 17a6b32..9f45680 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,9 @@ ## Web services en Python -Créer un web service en Python consiste à créer un script Python capable de traiter un fichier JSON fourni via l'entrée standard (sdtin) et de produire un fichier JSON similaire dans la sortie standard (stdout) +Créer un web service en Python consiste à créer un script Python capable de +traiter un fichier JSON fourni via l'entrée standard (sdtin) et de produire un +fichier JSON similaire dans la sortie standard (stdout). ### Exemple de fichier python @@ -19,9 +21,12 @@ sys.stdout.write('\n') ``` -Pour transformer un programme Python en web service, il est nécessaire de déclarer un point d’entrée (entrypoint) via la création d’un fichier .ini dans une arborescence spécifique (cf . Convention de nommage) +Pour transformer un programme Python en web service, il est nécessaire de +déclarer un point d’entrée (entrypoint) via la création d’un fichier `.ini` dans +une arborescence spécifique (cf . [Convention de nommage](#convention-de-nommage)). -Ce fichier contiendra la documentation au foamt OpenAPI, et une référence au fichier python a exécuter. +Ce fichier contiendra la documentation au format OpenAPI, et une référence au +fichier python a exécuter. #### Exemple de fichier .ini @@ -62,7 +67,8 @@ indent = env('indent', false) ``` -L'installation de paquet Python spécifique est possible en déclarant les paquests à installer à la racine de son web service dans un ficher `requirements.txt` +L'installation de paquet Python spécifique est possible en déclarant les paquets +à installer à la racine de son web service dans un ficher `requirements.txt`. ### Exemple de fichier requirements.txt @@ -76,7 +82,8 @@ ## Développer -Il est possible de tester localement (sur son poste) son webservice, dans un enviornement identique à celui de production, pour cela : +Il est possible de tester localement (sur son poste) son webservice, dans un +environnement identique à celui de production, pour cela : ### en Python @@ -95,17 +102,17 @@ Ensuite, le webservice est accessible à cette adresse . -**WARNING:** -Docker modifie le propiètaire des fichiers pour restaurer les permsisisons: - -```bash -make reset -``` +> **WARNING:** +> Docker modifie le propriétaire des fichiers. Pour restaurer les permissions: +> +> ```bash +> make reset +> ``` ## Tester -Des exemples de requêtes sont disponibles dans des fichers `examples.http`. -Ceux-ci peuvent être utilisés directement dans VSCode, avec l'extension REST Client (humao.rest-client). +Des exemples de requêtes sont disponibles dans des fichers `examples.http`. +Ceux-ci peuvent être utilisés directement dans VSCode, avec l'extension REST Client (humao.rest-client). Ils peuvent également être lancés en ligne de commande via [rest-cli](https://www.npmjs.com/package/rest-cli) ou via [dot-http](https://github.com/bayne/dot-http). @@ -161,11 +168,11 @@ ### Documentation OpenAPI -Chaque service, chaque route doit être documenté en respectant la norme OpenAPI 3.0 (swagger). +Chaque service, chaque route, doit être documenté en respectant la norme [OpenAPI](https://swagger.io/specification/) 3.0 (swagger). -La documentation de chaque route doit être placée dans le fichier .ini correspondant à sa route API. +La documentation de chaque route doit être placée dans le fichier `.ini` correspondant à sa route API. -Pour placer la document openapi dans les fichiers .ini, la syntaxe Swagger au format JSON doit être convertie au format "dot notation" +Pour placer la document openapi dans les fichiers `.ini`, la syntaxe Swagger au format JSON doit être convertie au format "dot notation" Exemple : @@ -177,18 +184,21 @@ post.requestBody.content.application/json.schema.$ref = #/components/schemas/anyValue ``` -Si vous souhaitez enrichir la documentation par défaut, en ajoutant des "tags", des components, il est possible d'ajouter un fichier standard `swagger.json` à la racine de votre instance. -Le serveur prendra en compte tout le fichier SAUF ce qui correspond aux informations concernant les routes -(qui doivent être placées dans le fichiers .ini) - +Si vous souhaitez enrichir la documentation par défaut, en ajoutant des _tags_, +des components, il est possible d'ajouter un fichier standard `swagger.json` à +la racine de votre instance. +Le serveur prendra en compte tout le fichier SAUF ce qui correspond aux +informations concernant les routes (qui doivent être placées dans le fichier +`.ini`). ### Déclarer la documentation Swagger Le répertoire `www-home` contient le HTML de la page d'accueil . -Pour ajouter une instance dans le menu déroulant (en haut à droite), il vous suffit de la déclarer dans `www-home/index.html` pour qu'elle -soit prise en compte. +Pour ajouter une instance dans le menu déroulant (en haut à droite), il vous +suffit de la déclarer dans `www-home/index.html` pour qu'elle soit prise en +compte. ## Convention de nommage @@ -217,20 +227,20 @@ La seconde partie décrit une **spécialité** du domaine. Cette spécificité est principalement liée à une image docker différente, comme -c'est le cas si les différents *web services* d'un domaine utilisent des -langages différents (C++, python, nodejs, etc.) +c'est le cas si les différents _web services_ d'un domaine utilisent des +langages différents (C++, python, nodejs, etc.). ### Nom des répertoires -Chaque instance donne accès à une arborescence de webservices. -Le nom de route dépend du nom des répertoires. +Chaque instance donne accès à une arborescence de webservices. +Le nom de route dépend du nom des répertoires. Les noms des répertoires doivent donc être choisis dans cette optique. -Il convient donc de respecter les pratiques communément admises dans la définition d'API de type REST. +Il convient donc de respecter les pratiques communément admises dans la définition d'API de type REST. En utilisant des noms de répertoires en minuscules, sans accent (mais pouvant contenir des chiffres) et de préférence en anglais. -Si le premier niveau caractérise obligatoirement la version, les suivants peuvent être adaptés selon le besoin. +Si le premier niveau caractérise obligatoirement la version, les suivants peuvent être adaptés selon le besoin. On veillera à créer un répertoire si et seulement si il propose plusieurs sous-répertoire ou fichiers. 1. Version des APIs (v1, v2, v3, etc.) @@ -246,9 +256,9 @@ ### Fichier d'exemple -Chaque répertoire dédié à une instance contiendra au moins un fichier `examples.http`. +Chaque répertoire dédié à une instance contiendra au moins un fichier `examples.http`. Ce fichier permet d'exécuter rapidement et simplement des exemples simples d'utilisation des webservices à travers VSCode -ou `restcli` (en ligne de commande). +ou `restcli` (en ligne de commande). Le format du fichier est celui précisé dans la documentation vscode . Voir aussi [Tester](#tester). @@ -256,10 +266,10 @@ ## Créer une version Afin de faciliter le déploiement (et de le limiter à un répertoire), on peut -utiliser les *helpers* du Makefile (`make version-major`, `make version-minor`, +utiliser les _helpers_ du Makefile (`make version-major`, `make version-minor`, `make version-patch`). -Ils se chargent de mettre un tag sur répertoire et de le pousser sur le dépôt. +Ils se chargent de mettre un _tag_ git sur répertoire et de le pousser sur le dépôt. Leur seul paramètre est le nom du répertoire. Exemple: