Swagger Codegen (Codegenerierung)

Swagger ist eine Sammlung von Open-Source-Tools, die rund um die OpenAPI-Spezifikation (früher als Swagger-Spezifikation bekannt) entwickelt wurden und zum Entwerfen, Erstellen, Dokumentieren und Konsumieren von RESTful-Webdiensten verwendet werden.

Swagger umfasst hauptsächlich:

  • Swagger Editor: Ein browserbasierter Editor, mit dem Sie OpenAPI-Spezifikationen schreiben können
  • Swagger UI: Eine visuelle API-Dokumentationsoberfläche, die Entwicklern ermöglicht, APIs interaktiv zu erkunden
  • Swagger Codegen: Generiert automatisch Client-Code und Server-Stubs basierend auf der OpenAPI-Spezifikation

Die OpenAPI-Spezifikation ist ein sprachunabhängiges Definitionsformat zur Beschreibung von RESTful-APIs.

OpenAPI ermöglicht es sowohl Menschen als auch Computern, die Fähigkeiten eines Dienstes zu entdecken und zu verstehen, ohne dass Zugriff auf Quellcode oder zusätzliche Dokumentation erforderlich ist.

Swagger Codegen (Codegenerierung)

Umgebungsvorbereitung

Bevor Sie beginnen, stellen Sie sicher, dass Folgendes auf Ihrem System installiert ist:

  • Java 8+
  • Maven (für Java-Projekte)
  • Git (zum Abrufen des Quellcodes)

Swagger Codegen installieren:

# 方法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

Client-SDK generieren

Java-Client-Generierung

Verwenden Sie die Petstore-API als Beispiel, um einen Java-Client zu generieren:

# 使用命令行工具
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

Die Struktur des generierten Client-SDK:

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

Verwendung des generierten Java-Clients:

Beispiel

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();
       
        // API-Schlüssel-Authentifizierung konfigurieren
        ApiKeyAuth apiKey = (ApiKeyAuth) defaultClient.getAuthentication("api_key");
        apiKey.setApiKey("DEIN API-SCHLÜSSEL");
       
        PetApi apiInstance = new PetApi();
        try {
            Pet result = apiInstance.getPetById(789L);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Ausnahme beim Aufruf von PetApi#getPetById");
            e.printStackTrace();
        }
    }
}

Python-Client-Generierung

Python-Client generieren:

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

Anwendungsbeispiel für den Python-Client:

Beispiel

import swagger_client
from swagger_client.rest import ApiException

# API-Client-Instanz erstellen
api_instance = swagger_client.PetApi()
api_client = api_instance.api_client

# API-Schlüssel festlegen
api_client.configuration.api_key['api_key'] = 'YOUR_API_KEY'

try:
    # Das Haustier mit der angegebenen ID abrufen
    pet = api_instance.get_pet_by_id(pet_id=789)
    print(pet)
except ApiException as e:
    print("Ausnahme beim Aufrufen von PetApi->get_pet_by_id: %s\n" % e)

Unterstützung für andere Sprachen

Swagger Codegen unterstützt mehrere Sprachen und Frameworks, einschließlich, aber nicht beschränkt auf:

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

Liste der unterstützten Sprachen anzeigen:

swagger-codegen langs

Server-Stub-Code generieren

Generierung von Spring-Server-Code

Generieren Sie einen Spring-Boot-Server-Stub:

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

Die Struktur des generierten Spring-Server-Codes:

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

Implementieren Sie die generierte Controller-Schnittstelle:

Beispiel

@Controller
public class PetApiController implements PetApi {
    @Override
    public ResponseEntity<Pet> getPetById(Long petId) {
        // API-Logik implementieren
        Pet pet = new Pet();
        pet.setId(petId);
        pet.setName("sample pet");
        pet.setStatus(Pet.StatusEnum.AVAILABLE);
        return ResponseEntity.ok(pet);
    }
}

Node.js-Server-Codegenerierung

Node.js-Servercode generieren:

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

Verwendungsbeispiel für den Node.js-Server:

Beispiel

// Geschäftslogik in der generierten Service-Datei implementieren
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 Erweitert

OpenAPI Generator vs Swagger Codegen

OpenAPI Generator ist ein Fork von Swagger Codegen, der 2018 mit der unabhängigen Entwicklung begann. Zu den wichtigsten Vorteilen gehören:

  • Aktivere Community-Wartung
  • Breitere Template-Unterstützung
  • Bessere Unterstützung für OpenAPI 3.0
  • Mehr Konfigurationsoptionen und Anpassungsmöglichkeiten

OpenAPI Generator installieren:

# 使用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 und grundlegende Verwendung

Grundlegende Verwendung:

# 显示帮助信息
openapi-generator help

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

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

Benutzerdefinierte Templates

Template-Grundlagen

OpenAPI Generator verwendet die Mustache-Template-Engine. Um den generierten Code anzupassen, müssen Sie:

  1. Standard-Templates abrufen
  2. Templates an Ihre Bedürfnisse anpassen
  3. Code mit benutzerdefinierten Templates generieren

Benutzerdefinierte Templates erstellen<
# 使用JAR文件获取特定语言的模板
java -jar openapi-generator-cli.jar author template \
  -g java \
  -o ./custom-templates/java

Beispiel einer Template-Datei (Java's api.mustache):

{{>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}}

Vorlage anwenden, um Code zu generieren

Code mithilfe benutzerdefinierter Vorlagen generieren:

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

Benutzerdefinierte Konfiguration

Globale Konfigurationsoptionen

OpenAPI Generator unterstützt verschiedene globale Konfigurationsoptionen:

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

Sprachspezifische Konfiguration

Verschiedene Generatoren haben ihre eigenen spezifischen Konfigurationsoptionen:

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

Verwenden von Konfigurationsdateien

Sie können eine Konfigurationsdatei erstellen, um allgemeine Einstellungen zu speichern:

config.json-Datei

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

Verwenden einer Konfigurationsdatei:

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

Praktische Projektbeispiele

API-Design von Grund auf

Entwerfen Sie Ihre API mit dem Swagger Editor:

  1. Besuchen Siehttps://editor.swagger.io/
  2. Erstellen Sie eine OpenAPI-Spezifikationsdatei:

Beispiel

openapi: 3.0.0
Info:
  title:Produktmanagement-API
  version: 1.0.0
  description:Eine RESTful-API zur Verwaltung von Produkten
servers:
  - url: https://api.example.com/v1
paths:
  /products:
    get:
      summary:Produktliste abrufen
      responses:
        '200':
          description:Erfolg
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product'
    post:
      summary:Ein neues Produkt erstellen
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductInput'
      responses:
        '201':
          description:Erstellung erfolgreich
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
  /products/{productId}:
    get:
      summary:Ein einzelnes Produkt abrufen
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description:Erfolg
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
components:
  schemas:
    Produkt:
      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

Vollständige Projektcode-Generierung

Generieren Sie ein vollständiges Projekt aus der entworfenen API-Spezifikation:

  1. Speichern Sie die API-Spezifikation alsproduct-api.yaml
  2. Generieren Sie Frontend- und Backend-Code:
# 生成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

Häufige Probleme und Lösungen

  1. Generierter Code kann nicht kompiliert werden

    • Stellen Sie sicher, dass die OpenAPI-Spezifikation den Standards entspricht
    • Benutzerdefinierte Vorlagen auf Syntaxfehler prüfen
    • Auf die neueste Version des Generators aktualisieren

  2. Benutzerdefinierte Vorlagen werden nicht wirksam

    • Stellen Sie sicher, dass der Vorlagenpfad korrekt ist
    • Prüfen Sie, ob der Name der Vorlagendatei mit der Originalvorlage übereinstimmt
    • Verwenden Sie absolute Pfade anstelle von relativen Pfaden

  3. Im generierten Code fehlen bestimmte Funktionen

    • Prüfen Sie, ob die OpenAPI-Spezifikation die erforderliche Funktionalität vollständig definiert
    • Bestätigen Sie, dass der richtige Generator und die richtigen Konfigurationsoptionen verwendet werden
    • Erwägen Sie, benutzerdefinierte Vorlagen zu verwenden, um zusätzliche Funktionalität hinzuzufügen

  4. Der generierte Code ist nicht mit bestehenden Projekten kompatibel

    • Verwenden Sie Konfigurationsoptionen, um Paketnamen und Namenskonventionen anzupassen
    • Passen Sie den Codestil mithilfe benutzerdefinierter Vorlagen an
    • Erwägen Sie, nur die API-Schnittstellen zu generieren und die spezifische Logik manuell zu implementieren

Erweiterte Funktionen und Best Practices

Versionsverwaltung

Bewährte Methoden für die Verwaltung von API-Versionen:

  1. Die Versionsnummer in der OpenAPI-Spezifikation eindeutig angeben
  2. Semantische Versionierung (SemVer) verwenden
  3. Unterschiedliche Basispfade für verschiedene Versionen der API verwenden
  4. Spezifikationsdateien für alle Versionen speichern

CI/CD-Integration

Codegenerierung in die CI/CD-Pipeline integrieren:

Beispiel

# GitHub Actions Workflow-Beispiel
name: API-Client generieren

auf:
  push:
    paths:
      - 'api-specs/**'

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
     
      - name: JDK einrichten
        uses: actions/setup-java@v2
        with:
          java-version: '11'
         
      - name: OpenAPI Generator installieren
        run: npm install @openapitools/openapi-generator-cli -g
       
      - name: Client generieren
        run: |
          openapi-generator generate \
            -i api-specs/product-api.yaml \
            -g typescript-fetch \
            -o ./generated-client
           
      - name: Commit und Push
        run: |
          git config --global user.name 'GitHub Actions'
          git config --global user.email '[email protected]'
          git add ./generiert-Client
          git commit -m "API-Client automatisch generieren"
          git push

Empfehlungen für Unternehmensanwendungen

Für Projekte auf Unternehmensebene:

  1. API-Spezifikationen zentral verwalten

    • Ein dediziertes Git-Repository zur Verwaltung von API-Spezifikationen verwenden
    • Einen Code-Review-Prozess implementieren, um die Qualität zu gewährleisten

  2. Einen Styleguide für generierten Code erstellen

    • Konsistente Namenskonventionen erstellen
    • Standards für die Fehlerbehandlung definieren
    • Einen einheitlichen Ansatz für die Authentifizierungsbehandlung entwerfen

  3. Generierten Code und handgeschriebenen Code mischen

    • Das grundlegende Framework und die Datenmodelle generieren
    • Komplexe Geschäftslogik manuell implementieren
    • Das Adapter-Muster verwenden, um generierten Code und handgeschriebenen Code zu isolieren

  4. Eine Microservices-Architektur in Betracht ziehen

    • Unabhängige API-Spezifikationen für jeden Microservice pflegen
    • Ein API-Gateway verwenden, um externe Schnittstellen zu vereinheitlichen
    • Client-Code zwischen Diensten durch Codegenerierung implementieren
Andere Erweiterungen