Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.
# Veröffentlichen der API-Dokumentation mithilfe der API Gateway-REST-API
Um die Dokumentation für eine API zu veröffentlichen, erstellen oder aktualisieren Sie einen Dokumentations-Snapshot bzw. rufen Sie einen Dokumentations-Snapshot ab und verknüpfen Sie diesen mit einer API-Stufe. Beim Erstellen eines Dokumentations-Snapshots können Sie ihn gleichzeitig mit einer eine API-Stufe verknüpfen.
**Topics**
+ [Erstellen eines Dokumentations-Snapshots und dessen Verknüpfen mit einer API-Stufe](#api-gateway-documenting-api-publishing-create-documentation-version-with-stage)
+ [Erstellen eines Dokumentations-Snapshots](#api-gateway-documenting-api-publishing-create-documentation-version)
+ [Aktualisieren eines Dokumentations-Snapshots](#api-gateway-documenting-api-publishing-update-documentation-version)
+ [Abrufen eines Dokumentations-Snapshots](#api-gateway-documenting-api-publishing-get-documentation-version)
+ [Verknüpfen eines Dokumentations-Snapshots mit einer API-Stufe](#api-gateway-documenting-api-publishing-stage-association)
+ [Herunterladen eines mit einer Stufe verknüpften Dokumentations-Snapshots](#api-gateway-documenting-api-publishing-export-documentation-version)
## Erstellen eines Dokumentations-Snapshots und dessen Verknüpfen mit einer API-Stufe
Um einen Snapshot der API-Dokumentationsbausteine zu erstellen und ihn zugleich mit einer API-Stufe zu verknüpfen, übermitteln Sie die folgende `POST`-Anforderung:
```
POST /restapis/restapi_id/documentation/versions HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"documentationVersion" : "1.0.0",
"stageName": "prod",
"description" : "My API Documentation v1.0.0"
}
```
Bei Erfolg gibt die Operation eine `200 OK`-Antwort zurück, die die neu erstellte `DocumentationVersion`-Instance als Nutzlast enthält.
Sie können auch einen Dokumentations-Snapshot erstellen, ohne ihn einer API-Stufe zuzuweisen, und dann [restapi:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html) aufrufen, um den Snapshot mit einer bestimmten API-Stufe zu verknüpfen. Sie können auch einen vorhandene Dokumentations-Snapshot aktualisieren oder abfragen und dann dessen Verknüpfung ändern. Diese Schritte werden in den nächsten vier Abschnitten gezeigt.
## Erstellen eines Dokumentations-Snapshots
Um einen Snapshot der Dokumentationsteile einer API zu erstellen, erstellen Sie eine neue [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html)Ressource und fügen Sie sie der [DocumentationVersions](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html)Sammlung der API hinzu:
```
POST /restapis/restapi_id/documentation/versions HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"documentationVersion" : "1.0.0",
"description" : "My API Documentation v1.0.0"
}
```
Bei Erfolg gibt die Operation eine `200 OK`-Antwort zurück, die die neu erstellte `DocumentationVersion`-Instance als Nutzlast enthält.
## Aktualisieren eines Dokumentations-Snapshots
Sie können einen Dokumentations-Snapshot nur aktualisieren, indem Sie die `description` Eigenschaft der entsprechenden [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html)Ressource ändern. Im folgenden Beispiel wird gezeigt, wie Sie die Beschreibung des Dokumentations-Snapshots gemäß seiner Versionskennung, `version`, aktualisieren (z. B. `1.0.0`).
```
PATCH /restapis/restapi_id/documentation/versions/version HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"patchOperations": [{
"op": "replace",
"path": "/description",
"value": "My API for testing purposes."
}]
}
```
Bei Erfolg gibt die Operation eine `200 OK`-Antwort zurück, die die aktualisierte `DocumentationVersion`-Instance als Nutzlast enthält.
## Abrufen eines Dokumentations-Snapshots
Um eine Momentaufnahme der Dokumentation zu erhalten, reichen Sie eine `GET` Anfrage für die angegebene [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html)Ressource ein. Im folgenden Beispiel wird gezeigt, wie Sie einen Dokumentations-Snapshot für eine bestimmte Versionskennung (1.0.0) abrufen.
```
GET /restapis//documentation/versions/1.0.0 HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
```
## Verknüpfen eines Dokumentations-Snapshots mit einer API-Stufe
Um die API-Dokumentation zu veröffentlichen, verknüpfen Sie einen Dokumentations-Snapshot mit einer API-Stufe. Sie müssen bereits eine API-Stufe erstellt haben, bevor Sie die Dokumentationsversion damit verknüpfen können.
Um einen Dokumentations-Snapshot mit einer API-Stufe über die [API Gateway-REST-API](https://docs.aws.amazon.com/apigateway/latest/api/) zu verknüpfen, rufen Sie den Vorgang [stage:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html) auf, um die gewünschte Dokumentationsversion für die Eigenschaft `stage.documentationVersion` festzulegen:
```
PATCH /restapis/RESTAPI_ID/stages/STAGE_NAME
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"patchOperations": [{
"op": "replace",
"path": "/documentationVersion",
"value": "VERSION_IDENTIFIER"
}]
}
```
## Herunterladen eines mit einer Stufe verknüpften Dokumentations-Snapshots
Nachdem eine Version der Dokumentationsteile einer Phase zugeordnet wurde, können Sie die Dokumentationsteile zusammen mit den API-Entitätsdefinitionen in eine externe Datei exportieren, indem Sie die API Gateway-Konsole, die API Gateway Gateway-REST-API SDKs, eine davon oder die AWS CLI für API Gateway verwenden. Der Vorgang ist mit dem für das Exportieren der API identisch. Das exportierte Dateiformat kann JSON oder YAML sein.
Mit der API Gateway-REST-API können Sie auch explizit den Abfrageparameter `extension=documentation,integrations,authorizers` so konfigurieren, dass die API-Dokumentationsbausteine, API-Integrationen und Genehmiger beim API-Export berücksichtigt werden. Standardmäßig sind die Dokumentationsbausteine enthalten, die Integrationen und Genehmiger aber vom Export einer API ausgeschlossen. Die Standardausgabe von einem API-Export eignet sich für die Verteilung der Dokumentation.
Um die API-Dokumentation in eine externe JSON-OpenAPI-Datei mit der API Gateway-REST-API zu exportieren, übermitteln Sie die folgende `GET`-Anforderung:
```
GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=documentation HTTP/1.1
Accept: application/json
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
```
Hier enthält das Objekt `x-amazon-apigateway-documentation` die Dokumentationsbausteine und die API-Entitätsdefinitionen beinhalten die von OpenAPI unterstützten Dokumentationseigenschaften. Die Ausgabe enthält keine Details zur Integration oder zu Lambda-Genehmigern (ehemals als benutzerdefinierte Genehmiger bezeichnet). Um beide Details einzuschließen, konfigurieren Sie `extensions=integrations,authorizers,documentation`. Um Details zu Integrationen, aber nicht zu Genehmigern einzuschließen, konfigurieren Sie `extensions=integrations,documentation`.
Sie müssen den `Accept:application/json`-Header in der Anforderung so konfigurieren, dass die Ausgabe in einer JSON-Datei erfolgt. Um eine YAML-Ausgabe zu erzeugen, ändern den Header der Anforderung in `Accept:application/yaml`.
Als Beispiel wird eine API verwendet, die eine einfache `GET`-Methode für die Stammressource (`/`) bereitstellt. Diese API verfügt über vier API-Entitäten, die in einer OpenAPI-Definitionsdatei definiert sind, eine für jeden der Typen `API`, `MODEL`, `METHOD` und `RESPONSE`. Jeder der `API`-, `METHOD`- und `RESPONSE`-Entitäten wurde ein Dokumentationsbaustein hinzugefügt. Durch Aufrufen des vorherigen Befehls zum Exportieren der Dokumentation erhalten wir die folgende Ausgabe, wobei die Dokumentationsbausteine im Objekt `x-amazon-apigateway-documentation` als Erweiterung einer OpenAPI-Standarddatei aufgeführt werden.
------
#### [ OpenAPI 3.0 ]
```
{
"openapi": "3.0.0",
"info": {
"description": "API info description",
"version": "2016-11-22T22:39:14Z",
"title": "doc",
"x-bar": "API info x-bar"
},
"paths": {
"/": {
"get": {
"description": "Method description.",
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
}
},
"x-example": "x- Method example"
},
"x-bar": "resource x-bar"
}
},
"x-amazon-apigateway-documentation": {
"version": "1.0.0",
"createdDate": "2016-11-22T22:41:40Z",
"documentationParts": [
{
"location": {
"type": "API"
},
"properties": {
"description": "API description",
"foo": "API foo",
"x-bar": "API x-bar",
"info": {
"description": "API info description",
"version": "API info version",
"foo": "API info foo",
"x-bar": "API info x-bar"
}
}
},
{
"location": {
"type": "METHOD",
"method": "GET"
},
"properties": {
"description": "Method description.",
"x-example": "x- Method example",
"foo": "Method foo",
"info": {
"version": "method info version",
"description": "method info description",
"foo": "method info foo"
}
}
},
{
"location": {
"type": "RESOURCE"
},
"properties": {
"description": "resource description",
"foo": "resource foo",
"x-bar": "resource x-bar",
"info": {
"description": "resource info description",
"version": "resource info version",
"foo": "resource info foo",
"x-bar": "resource info x-bar"
}
}
}
]
},
"x-bar": "API x-bar",
"servers": [
{
"url": "https://rznaap68yi.execute-api.ap-southeast-1.amazonaws.com/{basePath}",
"variables": {
"basePath": {
"default": "/test"
}
}
}
],
"components": {
"schemas": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
}
```
------
#### [ OpenAPI 2.0 ]
```
{
"swagger" : "2.0",
"info" : {
"description" : "API info description",
"version" : "2016-11-22T22:39:14Z",
"title" : "doc",
"x-bar" : "API info x-bar"
},
"host" : "rznaap68yi.execute-api.ap-southeast-1.amazonaws.com",
"basePath" : "/test",
"schemes" : [ "https" ],
"paths" : {
"/" : {
"get" : {
"description" : "Method description.",
"produces" : [ "application/json" ],
"responses" : {
"200" : {
"description" : "200 response",
"schema" : {
"$ref" : "#/definitions/Empty"
}
}
},
"x-example" : "x- Method example"
},
"x-bar" : "resource x-bar"
}
},
"definitions" : {
"Empty" : {
"type" : "object",
"title" : "Empty Schema"
}
},
"x-amazon-apigateway-documentation" : {
"version" : "1.0.0",
"createdDate" : "2016-11-22T22:41:40Z",
"documentationParts" : [ {
"location" : {
"type" : "API"
},
"properties" : {
"description" : "API description",
"foo" : "API foo",
"x-bar" : "API x-bar",
"info" : {
"description" : "API info description",
"version" : "API info version",
"foo" : "API info foo",
"x-bar" : "API info x-bar"
}
}
}, {
"location" : {
"type" : "METHOD",
"method" : "GET"
},
"properties" : {
"description" : "Method description.",
"x-example" : "x- Method example",
"foo" : "Method foo",
"info" : {
"version" : "method info version",
"description" : "method info description",
"foo" : "method info foo"
}
}
}, {
"location" : {
"type" : "RESOURCE"
},
"properties" : {
"description" : "resource description",
"foo" : "resource foo",
"x-bar" : "resource x-bar",
"info" : {
"description" : "resource info description",
"version" : "resource info version",
"foo" : "resource info foo",
"x-bar" : "resource info x-bar"
}
}
} ]
},
"x-bar" : "API x-bar"
}
```
------
Bei einem OpenAPI-kompatiblen Attribut, das in der `properties`-Map eines Dokumentationsbausteins definiert ist, fügt API Gateway das Attribut in die zugehörige API-Entitätsdefinition ein. Das Attribut `x-something` ist eine OpenAPI-Standarderweiterung. Diese Erweiterung wird in die API-Entitätsdefinition propagiert. Schauen Sie sich z. B. das Attribut `x-example` für die `GET`-Methode an. Ein Attribut wie `foo` ist nicht Teil der OpenAPI-Spezifikation und wird nicht in die dazugehörigen API-Entitätsdefinitionen eingefügt.
Wenn ein Dokumentations-Rendering-Tool (z. B. [OpenAPI UI](https://swagger.io/tools/swagger-ui/)) die API-Entitätsdefinitionen analysiert, um Dokumentationsattribute zu extrahieren, sind alle nicht mit OpenAPI kompatiblen `properties`-Attribute einer `DocumentationPart`-Instance nicht für das Tool verfügbar. Wenn jedoch ein Dokumentations-Rendering-Tool das Objekt `x-amazon-apigateway-documentation` analysiert, um Inhalte zu erhalten, oder wenn das Tool [restapi:documentation-parts](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) und [documenationpart:by-id](https://docs.aws.amazon.com/apigateway/latest/api/API_GetDocumentationPart.html) aufruft, um Dokumentationsbausteine von API Gateway abzurufen, sind alle Dokumentationsattribute für das Tool zur Anzeige verfügbar.
Um die Dokumentation mit API-Entitätsdefinitionen, die Integrationsdetails enthalten, in eine JSON-OpenAPI-Datei zu exportieren, übermitteln Sie folgende `GET`-Anforderung:
```
GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=integrations,documentation HTTP/1.1
Accept: application/json
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
```
Um die Dokumentation mit API-Entitätsdefinitionen, die Details zu Integrationen und Genehmigern enthalten, in eine YAML-OpenAPI-Datei zu exportieren, übermitteln Sie die folgende `GET`-Anforderung:
```
GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=integrations,authorizers,documentation HTTP/1.1
Accept: application/yaml
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
```
Um die API Gateway-Konsole zum Exportieren und Herunterladen der veröffentlichten Dokumentation einer API zu verwenden, befolgen Sie die Anweisungen unter [REST-API über die API-Gateway-Konsole exportieren](api-gateway-export-api.md#api-gateway-export-api-from-console).