Entwerfen Sie ein API-Schema mit ChatGPT

Schemata in OpenAPI 3.0 verstehen

In OpenAPI 3.0 wird ein Schema verwendet, um die Datenstruktur der Anforderungs- oder Antwortnutzlast einer API zu definieren. Auf diese Weise können das erwartete Format und die Datentypen der übertragenen Informationen beschrieben werden.

Ein Schema wird mithilfe des JSON-Schemas definiert, einem Standard zur Beschreibung der Struktur und Validierungsregeln für JSON-Daten. Die OpenAPI 3.0-Spezifikation umfasst eine erweiterte Teilmenge des JSON-Schemas, die zusätzliche Funktionen speziell für die API-Dokumentation bereitstellt, beispielsweise die Möglichkeit, Antwortcodes und Header zu beschreiben.

Die Schemadefinition kann in ein OpenAPI-Dokument eingefügt werdencomponents Abschnitt, in dem andere Teile des Dokuments darauf verweisen können. Ein Schema kann für einen Anforderungs- oder Antworttext, einen Anforderungs- oder Antwortheader oder einen Parameter definiert werden.

Zu den Eigenschaften, die in einem Schema definiert werden können, gehören:

type: Der Datentyp der Eigenschaft, zstring,integer,boolean, oderarray.

format: Ein Format für den Datentyp, zdate-time für einen Zeitstempel oderemail für eine E-Mail-Adresse.

properties: Eine Liste von Eigenschaften und ihren entsprechenden Schemata für ein Objekt.

items: Das Schema für jedes Element in einem Array.

required: Eine Liste der erforderlichen Eigenschaften für ein Objekt.

enum: Eine Liste möglicher Werte für eine Eigenschaft.

Durch die Definition von Schemata in OpenAPI 3.0 können API-Entwickler sicherstellen, dass ihre APIs gut dokumentiert sind und dass Kunden das erwartete Format und die Datentypen der übertragenen Informationen leicht verstehen können.

Schemata im Apigit-API-Design

Navigieren Sie zuAPI Specification Klicken Sie unter Ihrem Repository auf eine Beispiel-Spezifikationsdatei und klicken Sie im Standardansichtsmodus auf das ✏️-Symbol in der unteren linken Ecke der Seitenleiste.

Wählen Sie zunächst ein Beispielschema aus, zUser. Sobald Sie ein Schema ausgewählt haben, können Sie zwischen der Formularansicht und der Codeansicht wechseln. Benutzen wir dasUser Schema als Beispiel, das sechs Felder zum Entwerfen hat. Auch wenn es einfach erscheinen mag, können das Importtool von ChatGPT und Apigit dazu beitragen, den Prozess noch weiter zu vereinfachen.

Apigit importiert das Ergebnis von ChatGTP

Sie müssen lediglich Beispieldaten für Ihr Objekt generieren.

{
  "id": 10,
  "username": "theUser",
  "firstName": "John",
  "lastName": "James",
  "email": "john@email.com",
  "password": "12345",
  "phone": "12345",
  "userStatus": 1
}

Und dann bitten Sie ChatGTP, Ihnen die Schemadaten zu geben.

Von ChatGTP generierte Schemata

Was Sie erhalten, ist wie folgt.

{
    "$schema": "http://json-schema.org/draft-07/schema#",
        "title": "User",
        "type": "object",
        "properties": {
        "id": {
            "type": "integer",
                "description": "The ID of the user",
                "example": 10
        },
        "username": {
            "type": "string",
                "description": "The username of the user",
                "example": "theUser"
        },
        "firstName": {
            "type": "string",
                "description": "The first name of the user",
                "example": "John"
        },
        "lastName": {
            "type": "string",
                "description": "The last name of the user",
                "example": "James"
        },
        "email": {
            "type": "string",
                "format": "email",
                "description": "The email address of the user",
                "example": "john@email.com"
        },
        "password": {
            "type": "string",
                "description": "The password of the user",
                "example": "12345"
        },
        "phone": {
            "type": "string",
                "description": "The phone number of the user",
                "example": "12345"
        },
        "userStatus": {
            "type": "integer",
                "description": "The status of the user",
                "example": 1
        }
    },
    "required": ["id", "username", "firstName", "lastName", "email", "password", "phone", "userStatus"]
}

Um das von ChatGPT generierte JSON-SCHEMA zu importieren, führen Sie die folgenden Schritte aus:

1. Klick auf dasimport Taste.
2. WählenJSON SCHEMA aus den Optionen.
3. Fügen Sie den von ChatGPT generierten Code in das Textfeld ein.
4. KlickenOK oderImport um das Schema zu importieren.

Durch Befolgen dieser Schritte können Sie sicherstellen, dass Ihr JSON-Schema korrekt ist und Ihren Anforderungen entspricht.

1. Überprüfen Sie das Schema sorgfältig und prüfen Sie es auf Fehler oder Inkonsistenzen.
2. Nehmen Sie alle erforderlichen Änderungen am Schema vor, um Fehler zu korrigieren oder fehlende Informationen hinzuzufügen.