> ## Documentation Index
> Fetch the complete documentation index at: https://developers.jobhandy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Tooling und OpenAPI

> Importieren Sie den OpenAPI-Vertrag in API-Clients, erzeugen Sie typisierte Clients, validieren Sie Requests und kontrollieren Sie Vertragsupdates.

Das OpenAPI-3.1-Dokument ist der maßgebliche maschinenlesbare Vertrag der JobHandy Public API.

<Columns cols={2}>
  <Card title="OpenAPI JSON" icon="braces" href="https://assets.jobhandy.io/api-spec/jobhandy-public-api.openapi.json" arrow="true">
    Empfohlen für Tools, die JSON direkt verarbeiten.
  </Card>

  <Card title="OpenAPI YAML" icon="file-code" href="https://assets.jobhandy.io/api-spec/jobhandy-public-api.openapi.yaml" arrow="true">
    Semantisch gleichwertige, menschenlesbare Darstellung.
  </Card>
</Columns>

## In einen API-Client importieren

### Postman oder Insomnia

1. Laden Sie die JSON- oder YAML-Datei herunter.
2. Importieren Sie sie als OpenAPI-Spezifikation.
3. Konfigurieren Sie `https://api.jobhandy.io/v1` als Server, wenn der Client ihn nicht automatisch auswählt.
4. Speichern Sie `X-API-Key` in der geschützten Umgebung des Clients, nicht in einem gemeinsam genutzten Collection-Export.
5. Fügen Sie `X-Tenant-ID` nur dort hinzu, wo der Header erforderlich ist.
6. Entfernen oder deaktivieren Sie Beispiel-Secrets, bevor Sie den Workspace teilen.

## Client erzeugen

Beispiel mit OpenAPI Generator:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npx @openapitools/openapi-generator-cli generate \
  -i jobhandy-public-api.openapi.json \
  -g typescript-fetch \
  -o generated/jobhandy
```

Beispiel für einen C#-Client:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npx @openapitools/openapi-generator-cli generate \
  -i jobhandy-public-api.openapi.json \
  -g csharp \
  -o generated/jobhandy-csharp
```

Prüfen Sie generierten Code vor dem produktiven Einsatz. Generierte Clients implementieren nicht automatisch kundenspezifisches Secret Loading, Retry-Budgets, Reconciliation, Logging oder Datenschutzkontrollen.

## Vertragsvalidierung in CI

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart LR
    A[Gepinnte OpenAPI herunterladen] --> B[Syntax und Referenzen validieren]
    B --> C[Diff gegen übernommene Version]
    C --> D[Client oder Typen neu erzeugen]
    D --> E[Kompilieren]
    E --> F[Vertrags- und Integrationstests ausführen]
    F --> G[Übernahme freigeben]
```

Empfohlene Prüfungen:

* OpenAPI-3.1-Validierung ist erfolgreich
* alle `$ref`-Werte sind auflösbar
* `operationId`-Werte bleiben eindeutig
* generierter Code kompiliert
* Beispiele entsprechen ihren Schemas
* es treten keine unerwarteten Breaking Changes auf
* der produktive Server bleibt `https://api.jobhandy.io/v1`
* kein Development- oder Stage-Host wird in Kundenkonfigurationen eingeführt

## Übernommenen Vertrag pinnen

Archivieren Sie exakt die JSON- oder YAML-Datei, die für jedes Client-Release verwendet wurde. Dokumentieren Sie:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
client release
OpenAPI info.version
file checksum
adoption date
generator and configuration
breaking-change review result
```

Erzeugen Sie keinen produktiven Client automatisch aus einer ungeprüften Remote-Datei neu.