Facilitez l’adoption de votre API grâce aux SDK

<h2><strong>Swagger-codegen</strong></h2>

Swagger-codegen est un programme (open-source) permettant de générer un SDK dans un langage cible à partir d’une spécification OpenAPI (anciennement connue sous le nom de Swagger). Les SDK client sont générés dans plus de 40 langues différentes. Swagger-codegen simplifie ainsi le processus de construction afin que votre équipe puisse mieux se concentrer sur la mise en œuvre et l’adoption de votre API.

Le code source pour le Swagger Codegen peut être consulté sur <a href= »https://github.com/swagger-api/swagger-codegen »>GitHub</a> .

<h2><strong>Installation de swagger-codegen</strong></h2>

Avant de commencer il faut vérifier les <a href= »https://github.com/swagger-api/swagger-codegen#compatibility »>compatibilités</a> du projet swagger-codegen avec les spécifications OpenAPI.

Plus d’information sur l’ <a href= »https://github.com/swagger-api/swagger-codegen#prerequisites »>installation</a>

<pre># Avec Homebrew
brew install swagger-codegen

# A partir des sources
# Pour les utilisateurs de windows lancer les commandes sous powershell
# Prérequis installer java 8 ou plus
wget https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.31/swagger-codegen-cli-3.0.31.jar -O swagger-codegen-cli.jar

# Pour verifier l’installation
java -jar swagger-codegen-cli.jar –help

# Docker
docker pull swaggerapi/swagger-codegen-cli</pre>

<h2><strong>Comment générer un SDK ?</strong></h2>

Dans cet exemple nous allons prendre l’<a class= »notion-link-token notion-enable-hover » href= »https://petstore.swagger.io/ » target= »_blank » rel= »noopener noreferrer » data-token-index= »1″ data-reactroot= » »><span class= »link-annotation-unknown-block-id–341857816″>API petstore</span></a> comme API de référence. Commençons par générer un SDK en python comme ceci :

<pre># Creation d’un environnement virtuel
mkdir python &amp;&amp; \
python -m venv python/swagger-codegen-test &amp;&amp; \
source python/swagger-codegen-test/bin/activate</pre>

<pre># Génerer un SDK python

# Avec installation via homebrew
swagger-codegen generate -i https://petstore.swagger.io/v2/swagger.json -l python -o ./python

# Avec installation via les sources
java -jar swagger-codegen-cli.jar generate -i https://petstore.swagger.io/v2/swagger.json -l python -o ./python

# Avec docker
docker run –rm -v ${PWD}:/local swaggerapi/swagger-codegen-cli generate \
-i https://petstore.swagger.io/v2/swagger.json \
-l python \
-o /local/python</pre>

Cette commande va récupérer les spécifications OpenAPI de l’API petstore et générer le SDK dans le dossier “python”. On aurait pu aussi générer les SDK en go ou en javascript :

<pre># Génerer un SDK go

# Avec installation via homebrew
swagger-codegen generate -i https://petstore.swagger.io/v2/swagger.json -l go -o ./go

# Avec installation via les sources
java -jar swagger-codegen-cli.jar generate -i https://petstore.swagger.io/v2/swagger.json -l go -o ./go

# Avec docker
docker run –rm -v ${PWD}:/local swaggerapi/swagger-codegen-cli generate \
-i https://petstore.swagger.io/v2/swagger.json \
-l go \
-o /local/go</pre>

<pre># Génerer un SDK javascript

# Avec installation via homebrew
swagger-codegen generate -i https://petstore.swagger.io/v2/swagger.json -l javascript -o ./javascript

# Avec installation via les sources
java -jar swagger-codegen-cli.jar generate -i https://petstore.swagger.io/v2/swagger.json -l javascript -o ./javascript

# Avec docker
docker run –rm -v ${PWD}:/local swaggerapi/swagger-codegen-cli generate \
-i https://petstore.swagger.io/v2/swagger.json \
-l javascript \
-o /local/javascript</pre>

Jetons un œil à ce qui a été généré dans le dossier python :

<pre>tree -xa ./python</pre>

<pre>./python
├── .gitignore
├── .swagger-codegen
├── .swagger-codegen-ignore
├── .travis.yml
├── README.md
├── docs
├── git_push.sh
├── requirements.txt
├── setup.py
├── swagger-codegen-test
├── swagger_client
├── test
├── test-requirements.txt
└── tox.ini

5 directories, 9 files</pre>

Nous constatons que la commande a généré le code source de la bibliothèque, initialisé un projet git, généré un README expliquant comment utiliser la bibliothèque, les tests, et des scripts pour la gestion des dépendances. Le dossier semble complet. Vous pouvez installer ce package de plusieurs manières :

<pre># Installation via pip
# Si le package est stocké sur un repo github
pip install git+https://github.com/GIT_USER_ID/GIT_REPO_ID.git</pre>

<pre># Installation via setuptools
python ./python/setup.py install –user</pre>

Regardons maintenant si cela fonctionne. Écrivons un script pour récupérer tous les animaux avec le statut “sold”. Ce qui correspond à faire un GET sur l’endpoint <strong><a href= »https://petstore.swagger.io/#/pet/findPetsByStatus »>/pet/findByStatus</a></strong>

<pre># ./python/main.py

import swagger_client
from swagger_client.rest import ApiException

if __name__ == « __main__ »:
# Intanciation du client de la Pet API
api_instance = swagger_client.PetApi(
swagger_client.ApiClient(swagger_client.Configuration())
)

try:
# GET https://petstore.swagger.io/v2/pet/findByStatus
api_response = api_instance.find_pets_by_status([‘sold’])
print(api_response[0])
except ApiException as e:
print(« Exception when calling PetApi-&gt;FindPetsByStatus: %s\n » % e)</pre>

Le résultat :

<pre>{‘category’: {‘id’: 0, ‘name’: ‘Sharplaninec’},
‘id’: 46237,
‘name’: ‘string’,
‘photo_urls’: [‘string’],
‘status’: ‘sold’,
‘tags’: [{‘id’: 0, ‘name’: ‘Labrador’}]}</pre>

Parfait, nous avons eu la réponse attendue du serveur. En revanche, il reste encore un petit détail à corriger. Le nom du package ne correspond pas totalement à ce que l’on souhaite. Nous pouvons le modifier en passant un fichier de configuration à la commande :

<pre># Génerer un SDK python

# Avec installation via homebrew
swagger-codegen generate \
-i https://petstore.swagger.io/v2/swagger.json \
-l python \
-o ./python \
-c config.json

# Avec installation via les sources
java -jar swagger-codegen-cli.jar generate \
-i https://petstore.swagger.io/v2/swagger.json \
-l python \
-o ./python \
-c config.json

# Avec docker
docker run –rm -v ${PWD}:/local swaggerapi/swagger-codegen-cli generate \
-i https://petstore.swagger.io/v2/swagger.json \
-l python \
-o /local/python \
-c config.json</pre>

<pre>// config.json
{
« apiPackage » : « petstore »,
« packageName »: « petstore_api »,
« projectName »: « petstore_api »
}</pre>

Le nouveau main :

<pre># ./python/main.py

import petstore_api
from petstore_api.rest import ApiException

if __name__ == « __main__ »:
# Intanciation du client de la PetAPI
api_instance = petstore_api.PetApi(
petstore_api.ApiClient(petstore_api.Configuration())
)

try:
# GET https://petstore.swagger.io/v2/pet/findByStatus
api_response = api_instance.find_pets_by_status([‘sold’])
print(api_response[0])
except ApiException as e:
print(« Exception when calling PetApi-&gt;FindPetsByStatus: %s\n » % e)</pre>

Chaque langage dispose d’un fichier config qui lui est propre. Pour lister les champs disponibles pour un langage donné :

<pre>swagger-codegen config-help -l python</pre>

<pre>CONFIG OPTIONS
packageName
python package name (convention: snake_case). (Default: swagger_client)

projectName
python project name in setup.py (e.g. petstore-api).

packageVersion
python package version. (Default: 1.0.0)

packageUrl
python package URL.

sortParamsByRequiredFlag
Sort method arguments to place required parameters before optional parameters. (Default: true)

hideGenerationTimestamp
Hides the generation timestamp when files are generated. (Default: true)

library
library template (sub-template) to use (Default: urllib3)</pre>

<h2><strong>A vous de jouer !</strong></h2>

Dans cet article nous vous avons montré la simplicité avec laquelle il est possible aujourd’hui de générer des SDK à partir d’un swagger. Bien que les exemples de cet article soient assez simples, l’outil reste très permissif et offre la possibilité d’intégrer des templates de code personnalisés, sur lesquels le générateur s’appuiera. En revanche, cela implique la maîtrise des langages cibles. Swagger-codegen est bien évidemment un outil parmi d’autres permettant de résoudre le problème énoncé en préambule. Si vous aussi vous avez un jour fait face à cette problématique, n’hésitez pas à nous partager votre solution dans la zone commentaire.