Erste API in der Swagger-Benutzeroberfläche

Swagger UI ist ein Open-Source-Tool, das eine Benutzeroberfläche für eine OpenAPI-Spezifikation generiert, die es Benutzern ermöglicht, die API-Endpunkte zu visualisieren und mit ihnen zu interagieren. Das Tool wird vom Swagger-Projekt entwickelt und gewartet, das jetzt Teil der größeren OpenAPI-Initiative ist.

Swagger UI kann zum schnellen Testen und Erkunden einer API verwendet werden, ohne dass zusätzliche Tools oder Software erforderlich sind. Sobald eine OpenAPI-Spezifikation bereitgestellt wird, generiert Swagger UI eine interaktive Dokumentationsseite, die Informationen zu den Endpunkten, Parametern, Antworten und mehr der API enthält. Die Benutzeroberfläche wird dynamisch basierend auf den in der Spezifikation bereitgestellten Informationen generiert, was bedeutet, dass Änderungen an der API automatisch in der Dokumentation widergespiegelt werden.

Neben der Bereitstellung von Dokumentations- und Testfunktionen unterstützt Swagger UI auch verschiedene Funktionen wie Syntaxhervorhebung, Antwortvalidierung und Codegenerierung. Das Tool kann mit APIs verwendet werden, die mit einer beliebigen Programmiersprache erstellt wurden, und kann an das Branding und den Stil der API angepasst werden.

Heute werden wir unsere erste API in Swagger UI hinzufügen.

Feld des Servers

In einer OpenAPI-Spezifikation wird das Serverobjekt verwendet, um Informationen über den Server zu definieren, der die API hostet. Das Server-Objekt enthält mehrere Felder, die verwendet werden können, um Informationen wie URL, Protokoll und Beschreibung des Servers bereitzustellen. Hier sind die Felder, die in ein Serverobjekt aufgenommen werden können:

url: Dieses Feld gibt die Basis-URL des Servers an. Es ist ein Pflichtfeld und muss im Serverobjekt enthalten sein.

description: Dieses Feld enthält eine Beschreibung des Servers. Es ist ein optionales Feld und kann eingefügt werden, um zusätzliche Informationen über den Server bereitzustellen.

variables: Dieses Feld wird verwendet, um Variablen zu definieren, die im URL-Feld verwendet werden können. Variablen sind in geschweiften Klammern ({}) eingeschlossen und können verwendet werden, um Teile der URL darzustellen, die für verschiedene Umgebungen oder Anwendungsfälle angepasst werden können.

scheme: Dieses Feld gibt das vom Server verwendete Kommunikationsprotokoll an (z. B. HTTP, HTTPS usw.). Es ist ein optionales Feld und wird standardmäßig auf „http“ gesetzt, wenn es nicht angegeben ist.

headers: Dieses Feld wird verwendet, um Header anzugeben, die in Anfragen an den Server eingeschlossen werden sollen. Es ist ein optionales Feld und kann verwendet werden, um zusätzliche Informationen oder Authentifizierungsdaten bereitzustellen.

Hier ist ein Beispiel für ein Serverobjekt mit allen enthaltenen Feldern:

"servers": [
  {
    "url": "https://api.example.com/{version}",
    "description": "Example API Server",
    "variables": {
      "version": {
        "enum": ["v1", "v2"],
        "default": "v1"
      }
    },
    "scheme": "https",
    "headers": {
      "X-API-Key": {
        "description": "API key",
        "required": true
      }
    }
  }
]

Hier ist ein Beispiel für ein Serverobjekt für unsere erste API. Fügen Sie einen Server hinzu.

Tag-Feld

In einer OpenAPI-Spezifikation wird das Tag-Objekt verwendet, um ein Tag für eine Reihe verwandter Operationen zu definieren. Das Tag-Objekt enthält mehrere Felder, die verwendet werden können, um Informationen wie den Namen des Tags, eine Beschreibung und zugehörige Operationen bereitzustellen. Hier sind die Felder, die in ein Tag-Objekt aufgenommen werden können:

name: Dieses Feld gibt den Namen des Tags an. Es ist ein Pflichtfeld und muss im Tag-Objekt enthalten sein.

description: Dieses Feld enthält eine Beschreibung des Tags. Es ist ein optionales Feld und kann eingefügt werden, um zusätzliche Informationen über das Tag bereitzustellen.

externalDocs: Dieses Feld enthält einen Verweis auf zusätzliche Dokumentation für das Tag. Es ist ein optionales Feld und kann verwendet werden, um zusätzliche Informationen oder Ressourcen im Zusammenhang mit dem Tag bereitzustellen.

x-tag-info: Dieses Feld ist ein Erweiterungsfeld, das verwendet werden kann, um zusätzliche Informationen über das Tag bereitzustellen. Es ist ein optionales Feld und kann verwendet werden, um benutzerdefinierte Informationen oder Metadaten über das Tag bereitzustellen.

Hier ist ein Beispiel für ein Tag-Objekt mit allen enthaltenen Feldern:

"tags": [
  {
    "name": "pets",
    "description": "Operations related to pets",
    "externalDocs": {
      "description": "Find more info here",
      "url": "https://example.com/pets/info"
    },
    "x-tag-info": {
      "owner": "John Smith"
    }
  }
]

Hier ist ein Beispiel für ein Tag-Objekt für unsere erste API. Füge einen Tag hinzu.

Feld des Schemas

In einer OpenAPI-Spezifikation wird das Schema-Objekt verwendet, um die Struktur und die Datentypen eines Objekts zu beschreiben. Das Schema-Objekt enthält mehrere Felder, die verwendet werden können, um Informationen wie Typ, Format und Eigenschaften des Schemas bereitzustellen. Hier sind die Felder, die in ein Schemaobjekt aufgenommen werden können:

title: Dieses Feld gibt den Titel des Schemas an. Es ist ein optionales Feld und kann eingefügt werden, um einen für Menschen lesbaren Titel für das Schema bereitzustellen.

type: Dieses Feld gibt den Typ des Schemas an. Es ist ein erforderliches Feld und kann einer von mehreren möglichen Werten sein, z. B. „Zeichenfolge“, „Zahl“, „Ganzzahl“, „boolesch“, „Array“ oder „Objekt“.

format: Dieses Feld gibt das Format des Schemas an. Es ist ein optionales Feld und kann verwendet werden, um den Datentyp des Schemas weiter zu spezifizieren. Wenn der Typ beispielsweise "String" ist, kann das Formatfeld verwendet werden, um anzugeben, dass der String ein Datum oder eine Zeit ist.

description: Dieses Feld enthält eine Beschreibung des Schemas. Es ist ein optionales Feld und kann eingefügt werden, um zusätzliche Informationen über das Schema bereitzustellen.

properties: Dieses Feld gibt die Eigenschaften eines Objektschemas an. Es ist ein optionales Feld und kann verwendet werden, um die Eigenschaften und Datentypen der Eigenschaften eines Objekts zu definieren.

items: Dieses Feld gibt das Schema der Elemente in einem Array an. Es ist ein optionales Feld und kann verwendet werden, um den Datentyp der Elemente eines Arrays zu definieren.

required: Dieses Feld gibt die erforderlichen Eigenschaften eines Objektschemas an. Es ist ein optionales Feld und kann verwendet werden, um anzugeben, welche Eigenschaften eines Objektschemas erforderlich sind.

example: Dieses Feld enthält ein Beispiel für das Schema. Es ist ein optionales Feld und kann verwendet werden, um einen Beispielwert für das Schema bereitzustellen.

Hier ist ein Beispiel für ein Schemaobjekt mit allen enthaltenen Feldern:

{
  "type": "object",
  "title": "Person",
  "description": "A person schema",
  "properties": {
    "name": {
      "type": "string"
    },
    "age": {
      "type": "integer"
    },
    "email": {
      "type": "string",
      "format": "email"
    }
  },
  "required": [
    "name"
  ],
  "example": {
    "name": "John Smith",
    "age": 30,
    "email": "john.smith@example.com"
  }
}

Hier ist ein Beispiel für ein Schemaobjekt für unsere erste API. Fügen Sie ein Schema hinzu.

Feld von Wegen

In einer OpenAPI-Spezifikation wird das Pfadobjekt verwendet, um die verfügbaren Endpunkte (oder Routen) und Operationen an diesen Endpunkten zu definieren. Das Pfadobjekt ist eine Schlüsselwertzuordnung, bei der die Schlüssel die Endpunktpfade und die Werte Pfadelementobjekte sind. Hier sind die Felder, die in ein Pfadelementobjekt aufgenommen werden können:

HTTP-Methode: Es gibt mehrere HTTP-Methoden wie GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS und TRACE. Dieses Feld gibt die HTTP-Methode an, die der Endpunkt unterstützt.

summary: Dieses Feld bietet eine kurze Zusammenfassung des Endpunktvorgangs.

description: Dieses Feld enthält eine detaillierte Beschreibung des Endpunktvorgangs.

parameters: Dieses Feld gibt die Parameter an, die von der Endpunktoperation akzeptiert werden. Es kann ein Array von Parameterobjekten oder ein Verweis auf eine Parameterdefinition sein.

requestBody: Dieses Feld gibt den Anforderungshauptteil an, der von der Endpunktoperation erwartet wird. Es ist ein optionales Feld und kann ein RequestBody-Objekt oder ein Verweis auf eine Anforderungstextdefinition sein.

responses: Dieses Feld gibt die möglichen Antworten an, die von der Endpunktoperation zurückgegeben werden können. Es ist eine Key-Value-Map, bei der die Schlüssel die HTTP-Statuscodes und die Werte Response-Objekte sind.

callbacks: Dieses Feld gibt eine Karte möglicher Rückrufe an, die sich auf die übergeordnete Operation beziehen. Jeder Wert in der Map ist ein Callback-Objekt.

deprecated: Dieses Feld gibt an, ob die Endpunktoperation veraltet ist und nicht verwendet werden sollte.

Hier ist ein Beispiel für ein Pfadelementobjekt, das alle diese Felder enthält:

{
  "/pets": {
    "get": {
      "summary": "Get a list of pets",
      "description": "Returns a list of pets that are available for adoption.",
      "parameters": [
        {
          "name": "limit",
          "in": "query",
          "description": "The maximum number of pets to return.",
          "required": false,
          "schema": {
            "type": "integer"
          }
        }
      ],
      "responses": {
        "200": {
          "description": "A list of pets.",
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Pet"
                }
              }
            }
          }
        },
        "400": {
          "description": "Invalid input."
        },
        "401": {
          "description": "Unauthorized."
        },
        "500": {
          "description": "Server error."
        }
      }
    }
  }
}

Hier ist ein Beispiel für ein Pfadobjekt für unsere erste API. Fügen Sie einen Pfad hinzu.

Swagger UI kann zum schnellen Testen verwendet werden

DerTry it out Die Funktion in der Swagger-Benutzeroberfläche ermöglicht es Benutzern, mit einer API zu interagieren, indem sie Anfragen senden und Antworten empfangen. Es bietet eine Benutzeroberfläche zum Testen der API, ohne Code schreiben oder ein separates Tool verwenden zu müssen.

Wenn Sie auf die klickenTry it out neben einer API-Operation in der Swagger-Benutzeroberfläche können Sie Werte für die Parameter der Operation eingeben und eine Anfrage an die API senden. Swagger UI zeigt dann die Antwort an, die die API zurückgibt. Auf diese Weise können Sie das Verhalten einer API schnell testen und validieren, ohne die Swagger-Benutzeroberfläche verlassen zu müssen.

DerTry it out Die Funktion kann Ihnen auch dabei helfen, die Funktionen einer API zu erkunden und zu verstehen, wie Sie sie effektiv verwenden. Durch die Interaktion mit einer API in Echtzeit können Sie sehen, wie sie auf verschiedene Anfragen reagiert, und mehr über die zurückgegebenen Daten erfahren.

Hier ist ein Beispiel fürTry it out für unsere erste API. Try it out