Darstellung der API Dokumentation in Gateway API

APIDie API Gateway-Dokumentation besteht aus einzelnen DokumentationsteilenAPI, die bestimmten API Entitäten zugeordnet sind. Dazu gehören Ressourcen, Methoden, Anfragen, Antworten, Nachrichtenparameter (d. h. Pfad, Abfrage, Header) sowie Autorisierer und Modelle.

In API Gateway wird ein Dokumentationsteil durch eine DocumentationPartRessource repräsentiert. Die gesamte API Dokumentation wird durch die DocumentationPartsSammlung repräsentiert.

Das Dokumentieren einer API beinhaltet das Erstellen von DocumentationPart Instanzen, das Hinzufügen dieser zur DocumentationParts Sammlung und das Verwalten von Versionen der Dokumentationsteile, die API sich weiterentwickeln.

Dokumentationsbausteine

Eine DocumentationPartRessource ist ein JSON Objekt, das den für eine einzelne API Entität geltenden Dokumentationsinhalt speichert. Das Feld properties enthält den Dokumentationsinhalt in Form einer Übersicht von Schlüssel-Wert-Paaren. Ihre location Eigenschaft identifiziert die zugehörige API Entität.

Die Form einer Inhaltsübersicht wird von Ihnen, dem API Entwickler, bestimmt. 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 die Vererbung von Inhalten: Der Dokumentationsinhalt einer API Entität gilt für untergeordnete Elemente dieser API Entität. Weitere Informationen zur Definition von untergeordneten Entitäten und zur Inhaltsvererbung finden Sie unter Inhalte von einer API Entität mit allgemeinerer Spezifikation erben.

Lokation eines Dokumentationsbausteins

Die Location-Eigenschaft einer DocumentationPartInstanz identifiziert eine API Entität, für die der zugehörige Inhalt gilt. Bei der API Entität kann es sich um eine API REST API Gateway-Ressource handeln RestApi, z. B. eine Ressource, eine Methode MethodResponse, einen Autorisierer oder ein Modell. Die Entität kann auch ein Nachrichtenparameter sein, z. B. ein URL Pfadparameter, ein Abfragezeichenfolgenparameter, ein Anforderungs- oder Antwortheaderparameter, ein Anforderungs- oder Antworttext oder ein Antwortstatuscode.

Um eine API Entität anzugeben, legen Sie das Typattribut des location Objekts auf API AUTHORIZERMODEL,RESOURCE,METHOD,PATH_PARAMETER,QUERY_PARAMETER,REQUEST_HEADER, REQUEST_BODY RESPONSERESPONSE_HEADER, oder festRESPONSE_BODY.

Je type nach API Entität können Sie andere location Attribute angeben, darunter Methode, Name, Pfad und statusCode. Nicht alle diese Attribute sind für eine bestimmte API Entität gültig. 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. Es ist ein Fehler, ein ungültiges Feld in das location Feld a DocumentationPart für eine bestimmte API Entität aufzunehmen.

Nicht alle gültigen location-Felder sind erforderlich. Zum Beispiel type ist sowohl das gültige als auch das erforderliche location Feld aller 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 path Standardwert ist/, d. h. die Root-Ressource einesAPI. Der Standardwert für method oder statusCode ist *, d. h. jeder beliebige Methoden- bzw. Statuscodewert.

Inhalt eines Dokumentationsbausteins

Der properties Wert 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."
}

APIGateway akzeptiert zwar jede gültige JSON Zeichenfolge als Inhaltszuordnung, die Inhaltsattribute werden jedoch in zwei Kategorien unterteilt: diejenigen, die von Open erkannt werden können, API und solche, die nicht erkannt werden können. Im vorherigen Beispiel x-custom-info werden infodescription, und von Open API als API Standardobjekt, -Eigenschaft oder -Erweiterung von Open erkannt. my-infoEntspricht im Gegensatz dazu nicht der API Open-Spezifikation. APIGateway überträgt API Open-konforme Inhaltsattribute aus den zugehörigen DocumentationPart Instanzen in die API Entitätsdefinitionen. APIGateway überträgt die nicht konformen Inhaltsattribute nicht in die Entitätsdefinitionen. API

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"
    }
} 

Inhalte von einer API Entität mit allgemeineren Spezifikationen erben

Der Standardwert eines optionalen location Felds bietet eine gemusterte 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. APIGateway extrahiert die entsprechenden API Open-Dokumentationsattribute aus DocumentationPart der generischen API Entität und fügt sie in eine bestimmte API Entität ein, wobei die location Felder dem allgemeinen location Muster oder dem exakten Wert entsprechen, sofern der spezifischen Entität nicht bereits eine DocumentationPart Instanz zugeordnet ist. Dieses Verhalten wird auch als Inhaltsvererbung von einer API Entität mit allgemeineren Spezifikationen bezeichnet.

Inhaltsvererbung gilt nicht für bestimmte API Entitätstypen. Weitere Details finden Sie in der nachfolgenden Tabelle.

Wenn eine API Entität dem Standortmuster mehrerer DocumentationPart Entitäten entspricht, erbt die Entität den Dokumentationsteil mit den Standortfeldern mit 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 aus. 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 von "Invalid request error" wird in die API Open-Definitionen der 400 Fehlerantworten eingefügt, sofern sie nicht überschrieben wird.

{
    "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

Die folgende Tabelle zeigt die gültigen und erforderlichen Felder sowie die geltenden Standardwerte einer DocumentationPartRessource, die einem bestimmten Entitätstyp zugeordnet ist. API

{
    "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 eine Momentaufnahme der DocumentationPartsSammlung einer API und ist mit einer Versions-ID gekennzeichnet. Das Veröffentlichen der Dokumentation einer API beinhaltet das Erstellen einer Dokumentationsversion, das Verknüpfen dieser mit einer API Phase und das Exportieren dieser phasenspezifischen Version der API Dokumentation in eine externe Open-Datei. API In API Gateway wird ein Dokumentations-Snapshot als Ressource dargestellt. DocumentationVersion

Wenn Sie eine aktualisierenAPI, erstellen Sie neue Versionen vonAPI. In API Gateway verwalten Sie alle Dokumentationsversionen mithilfe der DocumentationVersionsSammlung.