Mit Sammlungen den Überblick behalten
Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.
OpenAPI
API Gateway unterstützt APIs, die mit der OpenAPI-Spezifikation Version 2.0 beschrieben werden.
Sie können Ihre API mit einem öffentlich verfügbaren REST-Framework wie Django oder Jersey implementieren.
Sie beschreiben die API in einer YAML-Datei, die als OpenAPI-Dokument bezeichnet wird. Auf dieser Seite werden einige Vorteile von OpenAPI erläutert. Außerdem wird die Grundstruktur eines OpenAPI-Dokuments gezeigt und Sie erhalten zusätzliche Informationen für den Einstieg in OpenAPI.
Vorteile
Einer der Hauptvorteile von OpenAPI ist die Dokumentation. Sobald Sie ein OpenAPI-Dokument haben, das Ihre API beschreibt, ist es einfach, eine Referenzdokumentation für diese zu erstellen.
Es gibt noch weitere Vorteile von OpenAPI. Beispiele:
Clientbibliotheken erstellen in Dutzenden Sprachen erstellen
Server-Stubs erstellen
Projekte nutzen, um die Konformität zu überprüfen und Beispiele zu generieren
Grundstruktur eines OpenAPI-Dokuments
Ein OpenAPI-Dokument beschreibt die Oberfläche Ihrer REST API und definiert folgende Daten:
den Namen und die Beschreibung der API
die individuellen Endunkte (Pfade) in der API
Die für Aufrufer verwendete Authentifizierungsmethode
Sollten Sie mit OpenAPI noch nicht vertraut sein, werfen Sie einen Blick auf die Website zur Swagger-Grundstruktur. Dort finden Sie ein OpenAPI-Beispieldokument (auch als Swagger-Spezifikation bezeichnet) und eine kurze Erläuterung der einzelnen Abschnitte der Datei.
Das folgende Beispiel veranschaulicht diese grundlegende Struktur:
swagger:"2.0"info:title:API_IDoptional-stringdescription:"Get the name of an airport from its three-letter IATA code."version:"1.0.0"host:DNS_NAME_OF_DEPLOYED_APIschemes:-"https"paths:"/airportName":get:description:"Get the airport name for a given IATA code."operationId:"airportName"parameters:-name:iataCodein:queryrequired:truetype:stringresponses:200:description:"Success."schema:type:string400:description:"The IATA code is invalid or missing."
Zusätzlich zur Grundstruktur können Sie mit der Datei openapi.yaml Folgendes konfigurieren:
Geben Sie im Feld title den Namen Ihrer API und in optional-string eine kurze Beschreibung ein.
Konfiguration eines Pfads für die Verwendung eines API-Schlüssels
Abhängig von der verwendeten Sprache können Sie ggf. ein OpenAPI-Dokument generieren. Java bietet Open-Source-Projekte für Jersey und Spring, mit denen OpenAPI-Dokumente aus Annotationen generiert werden können. Außerdem gibt es ein Maven-Plug-in.
Für Python- und Node-Entwickler könnte OpenAPI.Tools ein interessantes Projekt sein.
Die OpenAPI-Community arbeitet kontinuierlich an der Entwicklung von Tools, die Unterstützung beim Erstellen von OpenAPI-Dokumenten bieten (und diese in einigen Sprachen sogar automatisch generieren). Weitere Informationen finden Sie in der OpenAPI-Spezifikation.
[[["Leicht verständlich","easyToUnderstand","thumb-up"],["Mein Problem wurde gelöst","solvedMyProblem","thumb-up"],["Sonstiges","otherUp","thumb-up"]],[["Schwer verständlich","hardToUnderstand","thumb-down"],["Informationen oder Beispielcode falsch","incorrectInformationOrSampleCode","thumb-down"],["Benötigte Informationen/Beispiele nicht gefunden","missingTheInformationSamplesINeed","thumb-down"],["Problem mit der Übersetzung","translationIssue","thumb-down"],["Sonstiges","otherDown","thumb-down"]],["Zuletzt aktualisiert: 2025-08-18 (UTC)."],[[["\u003cp\u003eAPI Gateway supports APIs described using the OpenAPI specification, specifically version 2.0, allowing implementation with any public REST framework like Django or Jersey.\u003c/p\u003e\n"],["\u003cp\u003eOpenAPI documents, written in YAML, define the structure and surface of a REST API, including its name, description, endpoints, and authentication methods.\u003c/p\u003e\n"],["\u003cp\u003eUsing OpenAPI provides significant benefits, such as generating API reference documentation, client libraries, server stubs, and verification tools.\u003c/p\u003e\n"],["\u003cp\u003eAn OpenAPI document's basic structure includes defining the API's title, description, version, host, schemes, and paths, with an example provided for airport name retrieval.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eopenapi.yaml\u003c/code\u003e file can be used to configure various aspects of the API such as title, optional description, API key usage, security schemes, and OpenAPI extensions.\u003c/p\u003e\n"]]],[],null,["# OpenAPI overview\n================\n\nAPI Gateway supports APIs that are described using the OpenAPI specification, version\n[2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md).\nYour API can be implemented using any publicly available REST framework such as\n[Django](https://www.djangoproject.com/) or [Jersey](https://jersey.github.io/).\n\nYou describe your API in a `YAML` file referred to as an *OpenAPI\ndocument*. This page describes some of the benefits to using OpenAPI,\nshows a basic OpenAPI document, and provides additional information\nto help you get started with OpenAPI.\n| **Note:** For API Gateway, you use the same Open API syntax for defining your APIs as described in the Cloud Endpoints doc at [OpenAPI overview](/endpoints/docs/openapi/openapi-overview).\n\nBenefits\n--------\n\nOne of the primary benefits to using OpenAPI is for documentation; once you\nhave an OpenAPI document that describes your API, it is easy to generate\nreference documentation for your API.\n\nThere are other benefits to using OpenAPI. For example, you can:\n\n- Generate client libraries in dozens of languages\n- Generate server stubs\n- Use projects to verify your conformance and to generate samples\n\nBasic structure of an OpenAPI document\n--------------------------------------\n\nAn OpenAPI document describes the surface of your REST API, and defines information such as:\n\n- The name and description of the API\n- The individual endpoints (paths) in the API\n- How the callers are authenticated\n\nIf you are new to OpenAPI, take a look at the\n[Swagger basic structure](https://swagger.io/docs/specification/2-0/basic-structure/)\nwebsite, which provides a sample OpenAPI document (also referred to as a\nSwagger specification) and briefly explains each section of the file.\nThe following example illustrates this basic structure: \n\n```carbon\n swagger: \"2.0\"\n info:\n title: API_ID optional-string\n description: \"Get the name of an airport from its three-letter IATA code.\"\n version: \"1.0.0\"\n host: DNS_NAME_OF_DEPLOYED_API\n schemes:\n - \"https\"\n paths:\n \"/airportName\":\n get:\n description: \"Get the airport name for a given IATA code.\"\n operationId: \"airportName\"\n parameters:\n -\n name: iataCode\n in: query\n required: true\n type: string\n responses:\n 200:\n description: \"Success.\"\n schema:\n type: string\n 400:\n description: \"The IATA code is invalid or missing.\"\n```\n| **Note:** For API Gateway, use of the `host` property in your API definition is optional. You can either omit the `host` property entirely from the API definition or set it to the DNS name of the deployed API. API providers often set it to the DNS name when sharing the OpenAPI Spec with their API consumers. Do not set the `host` property to **null** or an empty value, as this will result in an error.\n\nIn addition to the basic structure, use the `openapi.yaml` file to configure:\n\n- The `title` field with the name of your API and an \u003cvar translate=\"no\"\u003eoptional-string\u003c/var\u003e with a brief description.\n- How to configure a path to use an [API key](/api-gateway/docs/authentication-method)\n- Various [security schemes](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#securitySchemeObject) for authentication\n- [OpenAPI extensions](/endpoints/docs/openapi/openapi-extensions)\n\nGenerating an OpenAPI document\n------------------------------\n\nDepending on what language you are using, you might be able to generate an\nOpenAPI document. In Java, there are open source projects for both\n[Jersey](https://jersey.github.io/)\nand [Spring](https://github.com/springfox/springfox)\nthat can generate an OpenAPI document from annotations. There is also a\n[Maven plugin](http://kongchen.github.io/swagger-maven-plugin/).\nFor Python and Node developers, [OpenAPI.Tools](https://openapi.tools/)\nmight be an interesting project.\n\nThe OpenAPI community is continually developing tools to help in the composition\n(and, for some languages, automatic generation) of OpenAPI documents. See the\n[The OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification)\nfor more.\n\nWhat's next\n-----------\n\n| **Note:** Because you use the same Open API syntax for the API Gateway as you used for Cloud Endpoints, these links refer to locations in the [Cloud Endpoints](/endpoints/docs/openapi/openapi-overview) documentation.\n\n- [OpenAPI extensions](/endpoints/docs/openapi/openapi-extensions)\n- [Unsupported OpenAPI features](/endpoints/docs/openapi/openapi-limitations)"]]
