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.

# Darstellung der API-Dokumentation in API Gateway
<a name="api-gateway-documenting-api-content-representation"></a>

Eine API Gateway-API-Dokumentation besteht aus einzelnen Bestandteilen (Bausteinen), die sich auf bestimmte API-Entitäten beziehen, z. B. API, Ressource, Methode, Anforderung, Antwort, Nachrichtenparameter (z. B. Pfad, Abfrage, Header) sowie Genehmiger und Modelle. 

In API Gateway wird ein Dokumentationsteil durch eine [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)Ressource dargestellt. Die API-Dokumentation als Ganzes wird durch die [DocumentationParts](https://docs.aws.amazon.com/apigateway/latest/api/API_GetDocumentationParts.html)Sammlung repräsentiert. 

Die Dokumentation einer API umfasst das Erstellen von `DocumentationPart`-Instances, das Hinzufügen dieser Instances zur `DocumentationParts`-Sammlung und die Pflege der verschiedenen Versionen der Dokumentationsbausteine, die im API-Entwicklungsprozess entstehen.

**Topics**
+ [Dokumentationsbausteine](#api-gateway-documenting-api-content-representation-documentation-parts)
+ [Dokumentationsversionen](#api-gateway-documenting-api-content-representation-documentation-versions)

## Dokumentationsbausteine
<a name="api-gateway-documenting-api-content-representation-documentation-parts"></a>

Eine [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)Ressource ist ein JSON-Objekt, das den Dokumentationsinhalt speichert, der für eine einzelne API-Entität gilt. Dazu gehören alle UTF-8-Inhalte und alle wichtigen Lokalisierungssprachen für Ihre Dokumentation. Das Feld `properties` enthält den Dokumentationsinhalt in Form einer Übersicht von Schlüssel-Wert-Paaren. Die Eigenschaft `location` identifiziert die zugehörige API-Entität. 

Sie, der API-Entwickler, bestimmen die Form einer Content Map. Der Wert eines Schlüssel-Wert-Paars kann eine Zeichenfolge, eine Zahl, ein boolescher Wert, ein Objekt oder ein Array sein. Die Form des `location`-Objekts hängt vom jeweiligen Entitätstyp ab. 

Die `DocumentationPart`-Ressource unterstützt das Vererben von Inhalten, das heißt, der Dokumentationsinhalt einer API-Entität gilt auch für die untergeordneten Elemente dieser API-Entität. Weitere Informationen zur Definition untergeordneter Entitäten und zur Vererbung von Inhalten finden Sie unter [Inherit Content from an API Entität of More General Specification](#api-gateway-documenting-api-content-inheritance). 

### Lokation eines Dokumentationsbausteins
<a name="api-gateway-documenting-api-content-representation-documentation-parts-target"></a>

Die [Location-Eigenschaft](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#location) einer [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)Instanz identifiziert eine API-Entität, für die der zugehörige Inhalt gilt. Die API-Entität kann eine API-Gateway-REST-API-Ressource sein [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html), z. B. [Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html), [Method [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html)](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html), [Authorizer](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html) oder [Model](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html). Die Entität kann auch ein Nachrichtenparameter sein, z. B. ein URL-Pfadparameter, ein Abfragezeichenfolge-Parameter, ein Anforderungs- oder Antwort-Header-Parameter, ein Anforderungs- oder Antworttext oder ein Antwortstatuscode. 

Um eine API-Entität anzugeben, wählen Sie für das Attribut [type](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#type) des Objekts `location` eine der folgenden Optionen: `API`, `AUTHORIZER`, `MODEL`, `RESOURCE`, `METHOD`, `PATH_PARAMETER`, `QUERY_PARAMETER`, `REQUEST_HEADER`, `REQUEST_BODY`, `RESPONSE`, `RESPONSE_HEADER` oder `RESPONSE_BODY`. 

Je nach `type` einer API-Entität können Sie auch andere `location`-Attribute angeben, z. B. [method](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#method), [name](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#name), [path](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#path) und [statusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#statusCode). Nicht alle diese Attribute gelten für eine bestimmte API-Entität. Zum Beispiel sind `type`, `path`, `name` und `statusCode` gültige Attribute der Entität `RESPONSE`; nur `type` und `path` sind gültige Lokationsattribute der Entität `RESOURCE`. Wenn Sie ein ungültiges Feld in der `location` eines `DocumentationPart` für eine bestimmte API-Entität angeben, führt dies zu einem Fehler.

Nicht alle gültigen `location`-Felder sind erforderlich. Beispielsweise ist `type` ein gültiges und erforderliches `location`-Feld für alle API-Entitäten. Die Attribute `method`, `path` und `statusCode` hingegen sind gültige, aber keine erforderlichen Attribute für die Entität `RESPONSE`. Sofern nicht explizit angegeben, übernimmt ein gültiges `location`-Feld seinen Standardwert. Der Standardwert für `path` ist `/`, d. h. die Stammressource einer API. Der Standardwert für `method` oder `statusCode` ist `*`, d. h. jeder beliebige Methoden- bzw. Statuscodewert.

### Inhalt eines Dokumentationsbausteins
<a name="api-gateway-documenting-api-content-representation-documentation-parts-content"></a>

Der Wert `properties` ist als JSON-Zeichenfolge kodiert. Der Wert `properties` enthält alle Informationen, die Sie auswählen, um Ihre Dokumentationsanforderungen zu erfüllen. Das folgende Beispiel zeigt eine gültige Content Map: 

```
{
  "info": {
    "description": "My first API with Amazon API Gateway."
  },
  "x-custom-info" : "My custom info, recognized by OpenAPI.",
  "my-info" : "My custom info not recognized by OpenAPI."
}
```

Auch wenn API Gateway jede gültige JSON-Zeichenfolge als Content Map akzeptiert, werden die Inhaltsattribute als zwei Kategorien behandelt: als Attribute, die von OpenAPI erkannt werden, und als Attribute, die nicht von OpenAPI erkannt werden. Im vorherigen Beispiel werden `info`, `description` und `x-custom-info` von OpenAPI als OpenAPI-Standardobjekt, -eigenschaft oder -erweiterung erkannt. Im Gegensatz dazu ist `my-info` nicht mit der OpenAPI-Spezifikation kompatibel. API Gateway verteilt OpenAPI-kompatible Inhaltsattribute in die API-Entitätsdefinitionen von den verknüpften `DocumentationPart`-Instances. Die nicht kompatiblen Inhaltsattribute werden von API Gateway nicht in die API-Entitätsdefinitionen verteilt. 

Ein weiteres Beispiel, bei dem `DocumentationPart` für eine `Resource`-Entität gilt:

```
{
    "location" : {
        "type" : "RESOURCE",
        "path": "/pets"
    },
    "properties" : {
        "summary" : "The /pets resource represents a collection of pets in PetStore.",
        "description": "... a child resource under the root...",
    }
}
```

Hier sind sowohl `type` als auch `path` gültige Felder zur Identifizierung des Ziels des Typs `RESOURCE`. Für die Stammressource (`/`) können Sie das Feld `path` weglassen.

```
{
    "location" : {
        "type" : "RESOURCE"
    },
    "properties" : {
        "description" : "The root resource with the default path specification."
    }
}
```

Dies entspricht der folgenden `DocumentationPart`-Instance:

```
{
    "location" : {
        "type" : "RESOURCE",
        "path": "/"
    },
    "properties" : {
        "description" : "The root resource with an explicit path specification"
    }
}
```



### Vererben von Inhalten aus einer API-Entität allgemeinerer Spezifikationen
<a name="api-gateway-documenting-api-content-inheritance"></a>

Der Standardwert eines optionalen `location`-Felds bietet eine musterhafte Beschreibung einer API-Entität. Unter Verwendung des Standardwerts im Objekt `location` können Sie eine allgemeine Beschreibung in der `properties`-Map zu einer `DocumentationPart`-Instance mit dieser Art von `location`-Muster hinzufügen. API Gateway extrahiert die entsprechenden OpenAPI-Dokumentationsattribute aus dem `DocumentationPart` der allgemeinen API-Entität und fügt sie in eine spezifische API-Entität mit den `location`-Feldern ein, die dem allgemeinen `location`-Muster entsprechen oder mit dem genauen Wert übereinstimmen, es sei denn, der betreffenden Entität ist bereits eine `DocumentationPart`-Instance zugeordnet. Dieses Verhalten wird auch als Vererbung von Inhalten aus einer API-Entität allgemeinerer Spezifikationen bezeichnet. 

Die Vererbung von Inhalten gilt für bestimmte API-Entitätentypen nicht. Weitere Details finden Sie in der nachfolgenden Tabelle.

Wenn eine API-Entität mit mehr als einem `DocumentationPart`-Lokationsmuster übereinstimmt, übernimmt die Entität den Dokumentationsbaustein mit den "location"-Feldern der höchsten Priorität und Spezifität. Die Rangfolge ist `path` > `statusCode`. Für den Abgleich mit dem `path`-Feld wählt API Gateway die Entität mit dem spezifischsten Pfadwert. In der folgenden Tabelle wird dies mit ein paar Beispielen veranschaulicht.


| Fall | `path` | `statusCode` | `name` | Anmerkungen | 
| --- | --- | --- | --- | --- | 
| 1 | /pets | \$1 | id |  Die mit diesem Lokationsmuster verknüpfte Dokumentation wird von den Entitäten übernommen, die mit dem Lokationsmuster übereinstimmen.  | 
| 2 | /pets | 200 | id |  Die mit diesem Lokationsmuster verknüpfte Dokumentation wird von den Entitäten übernommen, die mit dem Lokationsmuster übereinstimmen, sofern Fall 1 und 2 abgeglichen werden, da Fall 2 spezifischer ist als Fall 1.   | 
| 3 | /pets/petId | \$1 | id |  Die mit diesem Lokationsmuster verknüpfte Dokumentation wird von den Entitäten übernommen, die mit dem Lokationsmuster übereinstimmen, wenn Fall 1, 2 und 3 abgeglichen werden, da Fall 3 eine höhere Priorität hat als Fall 2 und spezifischer ist als Fall 1.  | 

Hier ein weiteres Beispiel für eine allgemeinere `DocumentationPart`-Instance im Vergleich zu einer spezifischeren Instance. Die folgende allgemeine Fehlermeldung `"Invalid request error"` wird in die OpenAPI-Definitionen der `400`-Fehlermeldungen eingefügt, sofern sie nicht überschrieben werden. 

```
{
    "location" : {
        "type" : "RESPONSE",
        "statusCode": "400"
    },
    "properties" : {
        "description" : "Invalid request error."
    }"
}
```

Mit der folgenden Überschreibung verfügen die `400`-Antworten auf alle Methoden der `/pets`-Ressource stattdessen über die Beschreibung `"Invalid petId specified"`. 

```
{
    "location" : {
        "type" : "RESPONSE",
        "path": "/pets",
        "statusCode": "400"
    },
    "properties" : "{
        "description" : "Invalid petId specified."
    }"
}
```

### Zulässige "location"-Felder für `DocumentationPart`
<a name="api-gateway-documenting-api-content-representation-target-specification"></a>

Die folgende Tabelle zeigt die gültigen und erforderlichen Felder sowie die geltenden Standardwerte einer [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)Ressource, die einem bestimmten Typ von API-Entitäten zugeordnet ist.


| API-Entität | Gültige "location"-Felder | Erforderliche "location"-Felder | Standardfeldwerte | Vererbbare Inhalte | 
| --- | --- | --- | --- | --- | 
| [API](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) |  <pre>{<br />    "location": {<br />        "type": "API" <br />    }, <br />    ... <br />}</pre>  | type | – | Nein | 
| [Ressource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) |  <pre>{ <br />    "location": { <br />        "type": "RESOURCE", <br />        "path": "resource_path" <br />    }, <br />    ... <br />}</pre>  | type | Der Standardwert von path ist /.  | Nein | 
| [Methode](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) |  <pre>{ <br />    "location": { <br />        "type": "METHOD", <br />        "path": "resource_path", <br />        "method": "http_verb" <br />    }, <br />    ... <br />}</pre>  | type | Die Standardwerte von path und method sind / bzw. \$1.  | Ja, Abgleich von path nach Präfix und von method nach beliebigen Werten  | 
| Abfrageparameter |  <pre>{ <br />    "location": { <br />        "type": "QUERY_PARAMETER", <br />        "path": "resource_path", <br />        "method": "HTTP_verb",<br />        "name": "query_parameter_name" <br />    }, <br />    ... <br />}</pre>  | type | Die Standardwerte von path und method sind / bzw. \$1.  | Ja, Abgleich von path nach Präfix und von method nach exakten Werten | 
| Anforderungstext |  <pre>{ <br />    "location": { <br />        "type": "REQUEST_BODY", <br />        "path": "resource_path", <br />        "method": "http_verb" <br />    }, <br />    ... <br />}</pre>  | type | Die Standardwerte von path und method sind / bzw. \$1.  | Ja, Abgleich von path nach Präfix und von method nach exakten Werten | 
| Parameter des Anforderungs-Headers |  <pre>{ <br />    "location": { <br />        "type": "REQUEST_HEADER", <br />        "path": "resource_path", <br />        "method": "HTTP_verb",<br />        "name": "header_name" <br />    }, <br />    ... <br />}</pre>  | type, name | Die Standardwerte von path und method sind / bzw. \$1.  | Ja, Abgleich von path nach Präfix und von method nach exakten Werten | 
| Pfadparameter der Anforderung |  <pre>{ <br />    "location": { <br />        "type": "PATH_PARAMETER", <br />        "path": "resource/{path_parameter_name}", <br />        "method": "HTTP_verb",<br />        "name": "path_parameter_name" <br />    }, <br />    ... <br />}</pre>  | type, name | Die Standardwerte von path und method sind / bzw. \$1.  | Ja, Abgleich von path nach Präfix und von method nach exakten Werten | 
| Antwort |  <pre>{ <br />    "location": { <br />        "type": "RESPONSE", <br />        "path": "resource_path", <br />        "method": "http_verb", <br />        "statusCode": "status_code" <br />    }, <br />    ... <br />}</pre>  | type | Die Standardwerte von path, method und statusCode sind /, \$1 bzw. \$1.  | Ja, Abgleich von path nach Präfix und von method und statusCode nach exakten Werten | 
| Antwort-Header |  <pre>{ <br />    "location": { <br />        "type": "RESPONSE_HEADER", <br />        "path": "resource_path", <br />        "method": "http_verb", <br />        "statusCode": "status_code", <br />        "name": "header_name" <br />    }, <br />    ... <br />}</pre>  | type, name | Die Standardwerte von path, method und statusCode sind /, \$1 bzw. \$1.  | Ja, Abgleich von path nach Präfix und von method und statusCode nach exakten Werten | 
| Antworttext |  <pre>{ <br />    "location": { <br />        "type": "RESPONSE_BODY", <br />        "path": "resource_path", <br />        "method": "http_verb", <br />        "statusCode": "status_code" <br />    }, <br />    ... <br />}</pre>  | type | Die Standardwerte von path, method und statusCode sind /, \$1 bzw. \$1.  | Ja, Abgleich von path nach Präfix und von method und statusCode nach exakten Werten | 
| [Authorizer](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html) |  <pre>{ <br />    "location": { <br />        "type": "AUTHORIZER", <br />        "name": "authorizer_name" <br />    }, <br />    ... <br />}</pre>  | type | – | Nein | 
| [Model](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) |  <pre>{ <br />    "location": { <br />        "type": "MODEL", <br />        "name": "model_name" <br />    }, <br />    ... <br />}</pre>  | type | – | Nein | 

## Dokumentationsversionen
<a name="api-gateway-documenting-api-content-representation-documentation-versions"></a>

Eine Dokumentationsversion ist eine Momentaufnahme der [DocumentationParts](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)Sammlung einer API und ist mit einer Versionskennung gekennzeichnet. Die Veröffentlichung der Dokumentation einer API umfasst das Erstellen einer Dokumentationsversion, deren Verknüpfung mit einer API-Stufe und das Exportieren dieser stufenspezifischen Version der API-Dokumentation in eine externe OpenAPI-Datei. In API Gateway wird ein Dokumentations-Snapshot als [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html)Ressource dargestellt. 

Wenn Sie eine API aktualisieren, erstellen Sie neue Versionen der API. In API Gateway verwalten Sie alle Dokumentationsversionen mithilfe der [DocumentationVersions](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html)Sammlung.