Darstellung der API-Dokumentation in API Gateway

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 Dokumentationsbaustein durch die Ressource DocumentationPart dargestellt. Die API-Dokumentation als Ganzes wird durch die Sammlung DocumentationParts dargestellt.

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.

Dokumentationsbausteine

Eine DocumentationPart-Ressource ist ein JSON-Objekt, in dem der Inhalt der Dokumentation zu einer API-Entität gespeichert wird. 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.

Lokation eines Dokumentationsbausteins

Die Eigenschaft location einer DocumentationPart-Instance identifiziert eine API-Entität, für die der zugehörige Inhalt gilt. Die API-Entität kann eine API Gateway-REST-API-Ressource wie RestApi, Resource, Method, MethodResponse, Authorizer oder Model sein. 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 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, name, path und 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

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

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.

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

In der folgenden Tabelle sind die zulässigen und erforderlichen Felder sowie die geltenden Standardwerte einer DocumentationPart-Ressource aufgeführt, die mit einer bestimmten Art von API-Entitäten verknüpft sind.

{
    "location": {
        "type": "API" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "RESOURCE", 
        "path": "resource_path" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "METHOD", 
        "path": "resource_path", 
        "method": "http_verb" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "QUERY_PARAMETER", 
        "path": "resource_path", 
        "method": "HTTP_verb",
        "name": "query_parameter_name" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "REQUEST_BODY", 
        "path": "resource_path", 
        "method": "http_verb" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "REQUEST_HEADER", 
        "path": "resource_path", 
        "method": "HTTP_verb",
        "name": "header_name" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "PATH_PARAMETER", 
        "path": "resource/{path_parameter_name}", 
        "method": "HTTP_verb",
        "name": "path_parameter_name" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "RESPONSE", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "RESPONSE_HEADER", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code", 
        "name": "header_name" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "RESPONSE_BODY", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "AUTHORIZER", 
        "name": "authorizer_name" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "MODEL", 
        "name": "model_name" 
    }, 
    ... 
}

Dokumentationsversionen

Eine Dokumentationsversion ist ein Snapshot der DocumentationParts-Sammlung einer API und mit einer Versions-ID 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-Ressource dargestellt.

Wenn Sie eine API aktualisieren, erstellen Sie neue Versionen der API. In API Gateway verwalten Sie alle Dokumentationsversionen über die Sammlung DocumentationVersions.