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 Sie die API Dokumentation mithilfe des API Gateways REST API

Um die Dokumentation für einen zu veröffentlichenAPI, zu erstellen, zu aktualisieren oder abzurufen und den Dokumentations-Snapshot dann einer API Phase zuzuordnen. Wenn Sie einen Dokumentations-Snapshot erstellen, können Sie ihn gleichzeitig auch einer API Phase zuordnen.

Erstellen Sie einen Dokumentations-Snapshot und verknüpfen Sie ihn mit einer API Phase

Um einen Snapshot der Dokumentationsteile eines API Benutzers zu erstellen und ihn gleichzeitig einer API Phase zuzuordnen, reichen Sie die folgende POST Anfrage ein:

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.

Alternativ können Sie einen Dokumentations-Snapshot erstellen, ohne ihn zuerst einer API Phase zuzuordnen, und dann restapi:update aufrufen, um den Snapshot einer bestimmten Phase zuzuordnen. API 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 eines API Benutzers zu erstellen, erstellen Sie eine neue DocumentationVersionRessource und fügen Sie sie der DocumentationVersionsSammlung von hinzu: API

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 DocumentationVersionRessource ä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 DocumentationVersionRessource ein. Im folgenden Beispiel wird gezeigt, wie Sie einen Dokumentations-Snapshot für eine bestimmte Versionskennung (1.0.0) abrufen.

GET /restapis/<restapi_id>/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

Ordnen Sie einer API Phase einen Dokumentations-Snapshot zu

Um die API Dokumentation zu veröffentlichen, verknüpfen Sie einen Dokumentations-Snapshot mit einer API Phase. Sie müssen bereits eine API Phase erstellt haben, bevor Sie die Dokumentationsversion der Phase zuordnen können.

Um mithilfe des APIGateways einen Dokumentations-Snapshot einer API Phase zuzuordnen RESTAPI, rufen Sie den Vorgang stage:update auf, um die gewünschte Dokumentationsversion für die Eigenschaft festzulegen: stage.documentationVersion

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, das API Gateway RESTAPI, eine davon oder die AWS CLI für Gateway verwenden. SDKs API Der Vorgang ist derselbe wie beim Exportieren vonAPI. Das exportierte Dateiformat kann JSON oder seinYAML.

Mithilfe des API Gateways können Sie den extension=documentation,integrations,authorizers Abfrageparameter auch explizit festlegen RESTAPI, um die API Dokumentationsteile, API Integrationen und Autorisierer in einen Export einzubeziehen. API Standardmäßig sind Dokumentationsteile enthalten, Integrationen und Autorisierer sind jedoch ausgeschlossen, wenn Sie einen exportieren. API Die Standardausgabe eines API Exports eignet sich für die Verteilung der Dokumentation.

Um die API Dokumentation mithilfe des API Gateways in eine externe JSON API Open-Datei zu exportieren RESTAPI, reichen Sie die folgende GET Anfrage ein:

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 x-amazon-apigateway-documentation Objekt die Dokumentationsteile und die API Entitätsdefinitionen die von Open unterstützten DokumentationseigenschaftenAPI. 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 Anfrage festlegen, um das Ergebnis in einer JSON Datei auszugeben. Um die YAML Ausgabe zu erzeugen, ändern Sie den Anforderungsheader inAccept:application/yaml.

Als Beispiel schauen wir uns eine an, API die eine einfache GET Methode für die Root-Ressource (/) verfügbar macht. Dabei API sind vier API Entitäten in einer API Open-Definitionsdatei definiert, eine für jeden der RESPONSE Typen APIMODEL,METHOD, und. Jeder der API-, METHOD- und RESPONSE-Entitäten wurde ein Dokumentationsbaustein hinzugefügt. Wenn wir den vorherigen Befehl zum Exportieren von Dokumentation aufrufen, erhalten wir die folgende Ausgabe, in der die Dokumentationsteile im x-amazon-apigateway-documentation Objekt als Erweiterung einer API Open-Standarddatei aufgeführt sind.

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

Für ein API Open-kompatibles Attribut, das in der properties Zuordnung eines Dokumentationsteils definiert ist, fügt API Gateway das Attribut in die zugehörige API Entitätsdefinition ein. Ein Attribut von x-something ist eine API Open-Standarderweiterung. Diese Erweiterung wird in die API Entitätsdefinition übernommen. Schauen Sie sich z. B. das Attribut x-example für die GET-Methode an. Ein Attribut like foo ist nicht Teil der API Open-Spezifikation und wird nicht in die zugehörigen API Entitätsdefinitionen eingefügt.

Wenn ein Tool zum Rendern von Dokumentation (z. B. Open API UI) die API Entitätsdefinitionen analysiert, um Dokumentationsattribute zu extrahieren, sind alle nicht Open API -konformen properties Attribute einer Instanz DocumentationPart für das Tool nicht verfügbar. Wenn jedoch ein Tool zum Rendern von Dokumentation das x-amazon-apigateway-documentation Objekt analysiert, um Inhalt abzurufen, oder wenn das Tool restapi:documentation-parts und documentationpart:by-id aufruft, um Dokumentationsteile von Gateway abzurufen, sind alle Dokumentationsattribute für das Tool zur Anzeige verfügbar. API

Um die Dokumentation mit API Entitätsdefinitionen, die Integrationsdetails enthalten, in eine Open-Datei zu exportieren, reichen Sie die folgende Anfrage ein: JSON API GET

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 Autorisierern enthalten, in eine YAML API Open-Datei zu exportieren, reichen Sie die folgende Anfrage ein: GET

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 veröffentlichte Dokumentation von mit der API Gateway-Konsole zu exportieren und herunterzuladenAPI, folgen Sie den Anweisungen unter. Exportieren REST API Sie mit der API Gateway-Konsole