Swagger Codegen (Génération de code)

Swagger est un ensemble d'outils open source construits autour de la spécification OpenAPI (anciennement connue sous le nom de spécification Swagger), utilisés pour concevoir, construire, documenter et consommer des services Web RESTful.

Swagger comprend principalement :

  • Swagger Editor: un éditeur basé sur navigateur qui vous permet d'écrire des spécifications OpenAPI
  • Swagger UI: une interface de documentation API visuelle qui permet aux développeurs d'explorer les API de manière interactive
  • Swagger Codegen: génère automatiquement du code client et des stubs serveur à partir de la spécification OpenAPI

La spécification OpenAPI est un format de définition indépendant du langage utilisé pour décrire des API RESTful.

OpenAPI permet aux humains et aux ordinateurs de découvrir et de comprendre les capacités d'un service sans avoir besoin d'accéder au code source ou à une documentation supplémentaire.

Swagger Codegen (Génération de code)

Préparation de l’environnement

Avant de commencer, assurez-vous que les éléments suivants sont installés sur votre système :

  • Java 8+
  • Maven (pour les projets Java)
  • Git (pour obtenir le code source)

Installer Swagger Codegen :

# 方法1: 使用homebrew (macOS)
brew install swagger-codegen

# 方法2: 从GitHub下载JAR文件
wget https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.36/swagger-codegen-cli-3.0.36.jar -O swagger-codegen-cli.jar
java -jar swagger-codegen-cli.jar help

Générer le SDK client

Génération du client Java

Utilisez l'API Petstore comme exemple pour générer un client Java :

# 使用命令行工具
swagger-codegen generate -i https://petstore.swagger.io/v2/swagger.json -l java -o ./java-client

# 或使用JAR文件
java -jar swagger-codegen-cli.jar generate \
  -i https://petstore.swagger.io/v2/swagger.json \
  -l java \
  -o ./java-client

La structure du SDK client généré :

java-client/
├── pom.xml                  # Maven项目文件
├── README.md                # 说明文档
├── src/
│   ├── main/
│   │   ├── java/           # 生成的Java代码
│   │   └── resources/      # 配置文件
│   └── test/               # 测试代码
└── .gitignore

Utilisation du client Java généré :

Exemple

import io.swagger.client.*;
import io.swagger.client.auth.*;
import io.swagger.client.model.*;
import io.swagger.client.api.PetApi;

public class Example {
    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
       
        // Configurer l'authentification par clé API
        ApiKeyAuth apiKey = (ApiKeyAuth) defaultClient.getAuthentication("api_key");
        apiKey.setApiKey("VOTRE CLÉ API");
       
        PetApi apiInstance = new PetApi();
        try {
            Pet result = apiInstance.getPetById(789L);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception lors de l'appel de PetApi#getPetById");
            e.printStackTrace();
        }
    }
}

Génération du client Python

Générer un client Python :

swagger-codegen generate -i https://petstore.swagger.io/v2/swagger.json -l python -o ./python-client

Exemple d'utilisation pour le client Python :

Exemple

import swagger_client
from swagger_client.rest import ApiException

# Créer une instance de client API
api_instance = swagger_client.PetApi()
api_client = api_instance.api_client

# Définir la clé API
api_client.configuration.api_key['api_key'] = 'YOUR_API_KEY'

try:
    # Récupérer l'animal avec l'ID spécifié
    pet = api_instance.get_pet_by_id(pet_id=789)
    print(pet)
except ApiException as e:
    print("Exception lors de l'appel de PetApi->get_pet_by_id: %s\n" % e)

Prise en charge d'autres langages

Swagger Codegen prend en charge plusieurs langages et frameworks, y compris, mais sans s'y limiter :

  • JavaScript/TypeScript (Node.js, Angular, React, etc.)
  • Ruby
  • PHP
  • C#/.NET
  • Go
  • Swift
  • Kotlin
  • Scala

Afficher la liste des langages pris en charge :

swagger-codegen langs

Générer le code stub du serveur

Génération du code serveur Spring

Générer un stub de serveur Spring Boot :

swagger-codegen generate \
  -i https://petstore.swagger.io/v2/swagger.json \
  -l spring \
  -o ./spring-server

La structure du code serveur Spring généré :

spring-server/
├── pom.xml                  # Maven项目文件
├── README.md                # 说明文档
├── src/
│   ├── main/
│   │   ├── java/           # 控制器接口和模型类
│   │   └── resources/      # 配置文件和静态资源
│   └── test/               # 测试代码
└── .gitignore

Implémenter l'interface de contrôleur générée :

Exemple

@Controller
public class PetApiController implements PetApi {
    @Override
    public ResponseEntity<Pet> getPetById(Long petId) {
        // Implémenter la logique de l'API
        Pet pet = new Pet();
        pet.setId(petId);
        pet.setName("sample pet");
        pet.setStatus(Pet.StatusEnum.AVAILABLE);
        return ResponseEntity.ok(pet);
    }
}

Génération de code serveur Node.js

Générer le code serveur Node.js :

swagger-codegen generate \
  -i https://petstore.swagger.io/v2/swagger.json \
  -l nodejs-server \
  -o ./nodejs-server

Exemple d'utilisation pour le serveur Node.js :

Exemple

// Implémenter la logique métier dans le fichier de service généré
module.exports.getPetById = function(petId) {
  return new Promise(function(resolve, reject) {
    var examples = {};
    examples['application/json'] = {
      "id": petId,
      "name": "sample pet",
      "status": "available"
    };
    resolve(examples[Object.keys(examples)[0]]);
  });
}

OpenAPI Generator avancé

OpenAPI Generator vs Swagger Codegen

OpenAPI Generator est un fork de Swagger Codegen, qui a commencé un développement indépendant en 2018. Ses principaux avantages incluent :

  • Maintenance communautaire plus active
  • Prise en charge plus étendue des gabarits
  • Meilleure prise en charge d'OpenAPI 3.0
  • Plus d'options de configuration et de capacités de personnalisation

Installer OpenAPI Generator :

# 使用npm安装
npm install @openapitools/openapi-generator-cli -g

# 使用Homebrew安装
brew install openapi-generator

# 下载JAR文件
wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/6.0.1/openapi-generator-cli-6.0.1.jar -O openapi-generator-cli.jar

Installation et utilisation de base

Utilisation de base :

# 显示帮助信息
openapi-generator help

# 生成Java客户端
openapi-generator generate \
  -i https://petstore.swagger.io/v2/swagger.json \
  -g java \
  -o ./java-client

# 列出支持的生成器
openapi-generator list

Gabarits personnalisés

Notions de base sur les gabarits

OpenAPI Generator utilise le moteur de gabarits Mustache. Pour personnaliser le code généré, vous devez :

  1. Obtenir les gabarits par défaut
  2. Modifier les gabarits pour répondre à vos besoins
  3. Générer du code à l'aide de gabarits personnalisés

Créer des gabarits personnalisés<
# 使用JAR文件获取特定语言的模板
java -jar openapi-generator-cli.jar author template \
  -g java \
  -o ./custom-templates/java

Exemple de fichier de gabarit (api.mustache de Java) :

{{>licenseInfo}}
package {{package}};

{{#imports}}import {{import}};
{{/imports}}

{{#operations}}
public interface {{classname}} {
    {{#operation}}
    {{#summary}}
    /**
     * {{summary}}
     * {{/summary}}
     {{#notes}}
     * {{notes}}
     {{/notes}}
     */
    {{#returnType}}{{returnType}} {{/returnType}}{{^returnType}}void {{/returnType}}{{operationId}}({{#allParams}}{{dataType}} {{paramName}}{{^-last}}, {{/-last}}{{/allParams}});
    
    {{/operation}}
}
{{/operations}}

Appliquer le modèle pour générer le code

Générer du code à l'aide de modèles personnalisés :

openapi-generator generate \
  -i https://petstore.swagger.io/v2/swagger.json \
  -g java \
  -o ./java-client-custom \
  -t ./custom-templates/java

Configuration personnalisée

Options de configuration globales

OpenAPI Generator prend en charge diverses options de configuration globales :

openapi-generator generate \
  -i spec.yaml \
  -g java \
  -o output \
  --api-package com.example.api \
  --model-package com.example.model \
  --package-name com.example \
  --git-repo-id my-repo \
  --git-user-id my-username

Configuration spécifique au langage

Les différents générateurs disposent de leurs propres options de configuration spécifiques :

# Java客户端生成器的特定选项
openapi-generator generate \
  -i spec.yaml \
  -g java \
  -o output \
  --library retrofit2 \
  --java8 true \
  --use-rx-java true

Utilisation des fichiers de configuration

Vous pouvez créer un fichier de configuration pour enregistrer les paramètres communs :

Fichier config.json

{
  "artifactId": "petstore-client",
  "groupId": "com.example",
  "library": "retrofit2",
  "apiPackage": "com.example.api",
  "modelPackage": "com.example.model",
  "invokerPackage": "com.example.client",
  "dateLibrary": "java8",
  "java8": true
}

Utilisation d'un fichier de configuration :

openapi-generator generate \
  -i spec.yaml \
  -g java \
  -o output \
  -c config.json

Cas pratiques de projet

Conception d'API à partir de zéro

Concevez votre API avec Swagger Editor :

  1. Visitezhttps://editor.swagger.io/
  2. Créez un fichier de spécification OpenAPI :

Exemple

openapi: 3.0.0
informations:
  title:API de gestion de produits
  version: 1.0.0
  description:Une API RESTful pour gérer les produits
servers:
  - url: https://api.example.com/v1
chemins:
  /products:
    get:
      summary:Obtenir la liste des produits
      responses:
        '200':
          description:Succès
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product'
    post:
      summary:Créer un nouveau produit
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductInput'
      responses:
        '201':
          description:Création réussie
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
  /products/{productId}:
    get:
      summary:Obtenir un seul produit
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description:Succès
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
components:
  schemas:
    Produit:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        price:
          type: number
        category:
          type: string
        createdAt:
          type: string
          format: date-time
    ProductInput:
      type: object
      required:
        - name
        - price
      properties:
        name:
          type: string
        price:
          type: number
        category:
          type: string

Génération complète du code du projet

Générer un projet complet à partir de la spécification API conçue :

  1. Enregistrer la spécification API sousproduct-api.yaml
  2. Générer le code frontend et backend :
# 生成Spring Boot服务端
openapi-generator generate \
  -i product-api.yaml \
  -g spring \
  -o ./product-service \
  --additional-properties=java8=true,dateLibrary=java8

# 生成React前端
openapi-generator generate \
  -i product-api.yaml \
  -g typescript-fetch \
  -o ./product-frontend \
  --additional-properties=supportsES6=true,npmName=product-api-client

Problèmes courants et solutions

  1. Le code généré ne compile pas

    • S'assurer que la spécification OpenAPI est conforme aux normes
    • Vérifier les erreurs de syntaxe dans les modèles personnalisés
    • Mettre à jour vers la dernière version du générateur

  2. Les modèles personnalisés ne prennent pas effet

    • Assurez-vous que le chemin du modèle est correct
    • Vérifiez que le nom du fichier de modèle correspond au modèle d'origine
    • Utilisez des chemins absolus au lieu de chemins relatifs

  3. Le code généré ne dispose pas de certaines fonctionnalités

    • Vérifiez si la spécification OpenAPI définit entièrement la fonctionnalité requise
    • Confirmez que le bon générateur et les bonnes options de configuration sont utilisés
    • Envisagez d'utiliser des modèles personnalisés pour ajouter des fonctionnalités supplémentaires

  4. Le code généré est incompatible avec les projets existants

    • Utilisez les options de configuration pour ajuster les noms des packages et les conventions de nommage
    • Ajustez le style de code à l'aide de modèles personnalisés
    • Envisagez de générer uniquement les interfaces API et d'implémenter la logique spécifique manuellement

Fonctionnalités avancées et bonnes pratiques

Gestion des versions

Bonnes pratiques pour la gestion des versions d'API :

  1. Spécifier clairement le numéro de version dans la spécification OpenAPI
  2. Utiliser le versionnement sémantique (SemVer)
  3. Utiliser des chemins de base différents pour les différentes versions de l'API
  4. Conserver les fichiers de spécification pour toutes les versions

Intégration CI/CD

Intégrer la génération de code dans le pipeline CI/CD :

Exemple

# Exemple de workflow GitHub Actions
name: Générer le client API

sur:
  push:
    chemins:
      - 'api-specs/**'

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
     
      - name: Configurer le JDK
        uses: actions/setup-java@v2
        with:
          java-version: '11'
         
      - name: Installer OpenAPI Generator
        run: npm install @openapitools/openapi-generator-cli -g
       
      - name: Générer le client
        run: |
          openapi-generator generate \
            -i api-specs/product-api.yaml \
            -g typescript-fetch \
            -o ./generated-client
           
      - name: Valider et pousser
        run: |
          git config --global user.name 'GitHub Actions'
          git config --global user.email '[email protected]'
          git add ./generated-client
          git commit -m "Générer automatiquement le client API"
          git push

Recommandations pour les applications d'entreprise

Pour les projets de niveau entreprise :

  1. Gérer les spécifications d'API de manière centralisée

    • Utiliser un dépôt Git dédié pour gérer les spécifications d'API
    • Mettre en place un processus de revue de code pour garantir la qualité

  2. Établir un guide de style pour le code généré

    • Créer des conventions de nommage cohérentes
    • Définir des normes de gestion des erreurs
    • Concevoir une approche unifiée de gestion de l'authentification

  3. Mélanger le code généré et le code écrit à la main

    • Générer le framework de base et les modèles de données
    • Implémenter manuellement la logique métier complexe
    • Utiliser le patron de conception Adaptateur pour isoler le code généré et le code écrit à la main

  4. Envisager une architecture de microservices

    • Maintenir des spécifications d'API indépendantes pour chaque microservice
    • Utiliser une passerelle API pour unifier les interfaces externes
    • Implémenter le code client entre les services via la génération de code
Autres extensions