Generator für JSON Antwortschemas in OpenAPI

Leite ein Antwortschema aus JSON Beispielen ab und erzeuge einen OpenAPI 3.0.3 YAML Pfad.

Antwortbeispiel und Endpunkt

JSON Antwortbeispiel

Wörtlicher Endpunktpfad

HTTP Methode

Erzeugtes OpenAPI YAML

openapi: 3.0.3
info:
  title: Generated API
  version: 1.0.0
paths:
  "/api/users":
    get:
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
components:
  schemas:
    Response:
      type: object
      required:
        - "id"
        - "name"
      properties:
        "id":
          type: integer
        "name":
          type: string

Funktionsweise

Füge ein JSON Antwortbeispiel ein, gib einen wörtlichen Endpunktpfad ein und wähle GET, POST, PUT oder DELETE. Der Generator leitet ein Schema für den Antwortkörper ab und setzt es in ein OpenAPI 3.0.3 YAML Dokument.

Verwende repräsentative Beispiele für mögliche Antwortvarianten. Wenn mehrere Objekte an derselben Array Stelle vorkommen, kombiniert der Generator ihre Eigenschaften. Eine Eigenschaft gilt nur dann als erforderlich, wenn sie in jedem beobachteten Objekt vorkommt.

Prüfe die abgeleiteten Typen und erforderlichen Felder, bevor du das YAML verwendest. Ergänze Request Bodies, Parameter, Authentifizierung, Fehlerantworten und Erklärungen für Pfadparameter selbst. Prüfe dann das vollständige Dokument mit einem OpenAPI Validator.

Nutze dieses Tool, wenn JSON Beispiele, aber kein Antwortschema vorliegen. Es dokumentiert nur den ausgewählten Pfad und die Methode anhand des angegebenen Beispiels.

Schritt für Schritt

JSON Antwortbeispiel einfügen
Wörtlichen Pfad eingeben und Methode wählen
Antwortschema prüfen und kopieren

Durchgerechnetes Beispiel

Für GET /api/users füge {"user":{"id":7,"name":"Ada"},"tags":["vip",null,7],"metrics":[{"count":2,"score":1.5},{"count":3,"active":true}]} ein. Das Beispiel enthält verschachtelte Objekte, gemischte Array Werte und zwei Metrikobjekte.

Die Ausgabe verlangt user, tags und metrics. Beide Metrikobjekte enthalten count, daher ist es dort ebenfalls erforderlich. score und active kommen jeweils nur in einem Objekt vor und sind deshalb optional. tags akzeptiert eine Zeichenfolge oder eine Ganzzahl. Beide beobachteten Typen sind nullable, da das Beispiel auch null enthält.

Wann dieses Tool hilft

Nutze den Generator, um beispielhafte JSON Antwortkörper beim Dokumentieren eines Pfads in ein erstes OpenAPI Antwortschema umzuwandeln.

Er ordnet beobachtete Antwortformen. Im erzeugten Dokument fehlen weiterhin die Request, Sicherheits, Fehler und Parameterdetails deiner API.

Häufige Fehler

Bei einem einzelnen Objekt erscheinen alle enthaltenen Eigenschaften als erforderlich. Um Unterschiede zwischen Antworten zu erkennen, gib mehrere repräsentative Objekte an derselben Array Stelle an.

Behandle die abgeleitete Ausgabe nicht als vollständige API Definition. Prüfe den Umgang mit null, optionale Felder, Array Varianten und wörtliche Pfade. Ergänze Request und Fehlerdetails, die dieses Tool nicht abdeckt.

Regeln zur Ableitung

Für jede Objektstelle gilt: erforderliche Schlüssel = Schlüssel, die in jedem beobachteten Objekt vorkommen.

Für jeden Wert gilt: abgeleitetes Schema = Vereinigung der beobachteten Typen außer null.

Wenn null mit einem bekannten Typ vorkommt, wird das typisierte Schema als nullable markiert.

Diese Ableitung basiert auf Beispielen und prüft keinen Vertrag zur Laufzeit. Ein einzelnes Beispiel zeigt nicht, welche Felder in Produktionsantworten fehlen dürfen.

Grenzen und Annahmen

Das Ergebnis beschreibt die beobachteten Beispielwerte. Es erkennt keine Felder, die in allen Beispielen fehlen, beweist keine Optionalität in der Produktion und leitet keinen Elementtyp aus einem leeren Array ab. Für einen Wert, der nur als null vorkommt, lässt sich kein Typ ableiten. Gemischte Werte werden als Alternativen dargestellt und sollten mit dem API Vertrag verglichen werden.

Wichtige Begriffe

OpenAPI Dokument: Ein OpenAPI Dokument beschreibt Pfade, Vorgänge, Eingaben, Antworten und weitere API Details in einem maschinenlesbaren Format.
Schema: Ein Schema beschreibt die erwartete Datenstruktur und Werttypen, etwa ein Objekt mit benannten Eigenschaften.
Erforderliche Eigenschaft: In dieser Ausgabe bedeutet erforderlich, dass die Eigenschaft in jedem beobachteten Objekt an dieser Stelle vorkam. Das beweist kein Verhalten in der Produktion.

FAQ

Wie wird aus dem Beispiel ein Antwortschema?

Der Generator untersucht jeden Wert im JSON Beispiel. Er erstellt Objekteigenschaften, prüft alle Array Elemente und kombiniert beobachtete Typen bei Bedarf mit anyOf. Das tags Array im Beispiel enthält Zeichenfolgen, null und eine Ganzzahl. Das Elementschema erlaubt daher eine nullable Zeichenfolge oder eine nullable Ganzzahl.

Wie werden null und verschiedene Typen dargestellt?

Objekte werden zu Schemas mit Eigenschaften. Eine Eigenschaft gilt als erforderlich, wenn sie in jedem beobachteten Objekt an dieser Stelle vorkommt. Unterschiedliche beobachtete Typen verwenden anyOf. Wenn null und ein weiterer Typ vorkommen, erhält das typisierte Schema nullable: true. Für einen Wert, der nur als null vorkommt, lässt sich kein Typ ableiten und das Schema bleibt uneingeschränkt.

Was enthält das erzeugte Dokument?

Das Dokument enthält einen Pfad, die gewählte Methode GET, POST, PUT oder DELETE und eine erfolgreiche JSON Antwort mit Status 200. Das Schema liegt unter components und wird von der Antwort referenziert. Der Generator erstellt weder Request Body noch Parameter, Sicherheitsregeln, Fehlerantworten oder Header.

Kann ich einen Pfadparameter wie eine ID eingeben?

Der Pfad muss ein wörtlicher Pfad sein und mit einem Schrägstrich beginnen, etwa /api/users. Pfade mit geschweiften Klammern werden abgelehnt, da eine Vorlage wie /api/users/{id} zusätzlich einen deklarierten Pfadparameter benötigt, den der Generator nicht ergänzt.

Erzeugt oder prüft das Tool einen vollständigen API Vertrag?

Nein. Die Ausgabe beschreibt den Antwortkörper eines Beispiels. Sie leitet keine Request Schemas ab und prüft das erzeugte YAML nicht gegen die OpenAPI Spezifikation. Ergänze weitere Vorgänge und Antwortdetails selbst und prüfe anschließend das vollständige Dokument mit einem OpenAPI Validator.

Quellen

OpenAPI Initiative: OpenAPI Specification 3.0.3