Felder in OpenAPI

OpenAPI (früher bekannt als Swagger) ist eine Spezifikation zum Erstellen von APIs (Application Programming Interfaces). Es bietet eine Standardmethode zum Definieren, Dokumentieren und Verwenden von RESTful-APIs. Die OpenAPI-Spezifikation ist im YAML- oder JSON-Format geschrieben und enthält eine Reihe von Feldern, die verwendet werden, um verschiedene Aspekte der API zu definieren.

Hier sind einige der am häufigsten verwendeten Felder in OpenAPI:

openapi: Gibt die Version der verwendeten OpenAPI-Spezifikation an.
info: Enthält Informationen über die API, wie z. B. Titel, Beschreibung, Version und Kontaktdaten.
servers: Gibt die Server an, auf denen die API gehostet wird.
paths: Definiert die Endpunkte (URLs) der API und die HTTP-Methoden (GET, POST, PUT, DELETE usw.), die für den Zugriff darauf verwendet werden können.
components: Enthält wiederverwendbare Elemente der API, z. B. Schemata, Sicherheitsschemata und Antworten.
security: Gibt die Sicherheitsschemata an, die die API verwendet.
tags: Stellt Metadaten zum Gruppieren und Organisieren von Vorgängen und Endpunkten bereit.
externalDocs: Enthält Links zu externer Dokumentation im Zusammenhang mit der API.

Dies sind nur einige Beispiele für Felder, die in einer OpenAPI-Spezifikation verwendet werden können. Die vollständige Liste der Felder finden Sie in der offiziellen OpenAPI-Spezifikationsdokumentation.

Wie trägt Apigit zum Ausfüllen dieser Felder bei?

Obwohl nicht alle Felder in einer OpenAPI-Spezifikation unbedingt erforderlich sind, gibt es bestimmte Felder, die enthalten sein müssen, um sicherzustellen, dass die Spezifikation gültig und vollständig ist. Hier sind einige der Must-Have-Felder in einer OpenAPI-Spezifikation:

openapi: Gibt die Version der verwendeten OpenAPI-Spezifikation an. Dieses Feld ist erforderlich und muss auf der Stammebene der Spezifikation enthalten sein.
info: Enthält Informationen über die API, wie z. B. Titel, Beschreibung, Version und Kontaktdaten. Dieses Feld ist erforderlich und muss auch auf der Stammebene der Spezifikation enthalten sein.
paths: Definiert die Endpunkte (URLs) der API und die HTTP-Methoden (GET, POST, PUT, DELETE usw.), die für den Zugriff darauf verwendet werden können. Dieses Feld ist ebenfalls erforderlich und muss auf der Stammebene der Spezifikation enthalten sein.
servers: Gibt die Server an, auf denen die API gehostet wird. Dieses Feld ist nicht unbedingt erforderlich, es wird jedoch empfohlen, es aufzunehmen, um Informationen zu den Servern bereitzustellen, auf denen die API gehostet wird.
components: Enthält wiederverwendbare Elemente der API, z. B. Schemata, Sicherheitsschemata und Antworten. Dieses Feld ist nicht unbedingt erforderlich, es wird jedoch empfohlen, es für eine bessere Organisation und Wiederverwendbarkeit der Spezifikation aufzunehmen.

Dies sind die wesentlichen Felder, die in einer OpenAPI-Spezifikation enthalten sein müssen, um sicherzustellen, dass sie gültig und vollständig ist. Andere Felder wie zsecurity,tags, UndexternalDocs können je nach den Anforderungen der API und dem in der Spezifikation erforderlichen Detaillierungsgrad ebenfalls enthalten sein.

Um Ihrem Apigit-Dashboard eine API-Spezifikation hinzuzufügen, klicken Sie auf das „+“-Zeichen in der oberen linken Ecke. Geben Sie einen Pfadnamen wie „test/test.json“ zusammen mit anderen relevanten Informationen wie „Titel“ und „Version“ ein. Eine leere Datei hilft, alle diese erforderlichen Felder auszufüllen.

Erstellen Sie eine leere Spezifikationsdatei

Dann würde Ihr JSON-Code wie folgt aussehen.

{
  "openapi": "3.0.3",
  "info": {
    "title": "titlet",
    "description": "just a test",
    "termsOfService": "",
    "contact": {
      "email": ""
    },
    "license": {
      "name": "Apache 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
    },
    "version": "1.0"
  },
  "externalDocs": {
    "description": "Find out more about spec",
    "url": ""
  },
  "servers": [],
  "tags": [
    {
      "name": "Default",
      "description": ""
    }
  ],
  "paths": {},
  "components": {
    "schemas": {},
    "securitySchemes": {}
  }
}

Wie hilft Apigit mehr?

Um zu veranschaulichen, wie Apigit beim Ausfüllen eines Felds im Formularformat hilft, finden Sie hier einige Beispiele. HinzufügenField parameter InForm

Dann würde Ihr JSON-Code wie folgt aussehen.

"components": {
    "schemas": {},
    "securitySchemes": {},
    "parameters": {
      "petId": {
        "in": "path",
        "required": true,
        "description": "",
        "schema": {
          "type": "string"
        },
        "name": "PetId"
      }
    }
  }

HinzufügenField path InForm

Dann würde Ihr JSON-Code wie folgt aussehen.

"paths": {
    "/getPet/{petId}": {
      "get": {
        "description": "",
        "operationId": "",
        "tags": [],
        "parameters": [],
        "requestBody": {},
        "responses": {
          "511": {}
        }
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/petId"
        }
      ]
    }
  },