Importieren einer API-Dokumentation

Wie beim Importieren von API-Entitätsdefinitionen können Sie Dokumentationsbausteine von einer externen OpenAPI-Datei in eine API in API Gateway importieren. Sie geben die zu importierenden Dokumentationsbausteine in der x-amazon-apigateway-documentation-Objekt-Erweiterung in einer gültigen OpenAPI-Definitionsdatei an. Durch das Importieren der Dokumentation werden die vorhandenen API-Entitätsdefinitionen nicht geändert.

Sie haben die Möglichkeit, die neu angegebenen Dokumentationsbausteine in vorhandene Dokumentationsbausteine in API Gateway zusammenzuführen oder die vorhandenen Dokumentationsbausteine zu überschreiben. Im MERGE-Modus wird ein neuer Dokumentationsbaustein, der in der OpenAPI-Datei definiert ist, der DocumentationParts-Sammlung der API hinzugefügt. Wenn bereits ein importierter DocumentationPart vorhanden ist, ersetzt ein importiertes Attribut jeweils einen vorhandenen Baustein, sofern einer der beiden unterschiedlich ist. Andere vorhandene Dokumentationsattribute bleiben davon unberührt. Im Modus OVERWRITE wird die gesamte DocumentationParts-Sammlung entsprechend der importierten OpenAPI-Definitionsdatei ersetzt.

Importieren der Dokumentationsbausteine mit der API Gateway-REST-API

Um eine API-Dokumentation mit der API Gateway-REST-API zu importieren, rufen Sie den Vorgang documentationpart:import auf. Das folgende Beispiel zeigt, wie vorhandene Dokumentationsbausteine einer API mit einer einzigen GET / -Methode überschrieben werden. Bei Erfolg wird eine 200 OK-Antwort zurückgegeben.

OpenAPI 3.0

PUT /restapis/<restapi_id>/documentation/parts&mode=overwrite&failonwarnings=true
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

{
   "openapi": "3.0.0",
   "info": {
      "description": "description",
      "version": "1",
      "title": "doc"
   },
   "paths": {
      "/": {
         "get": {
            "description": "Method description.",
            "responses": {
               "200": {
                  "description": "200 response",
                  "content": {
                     "application/json": {
                        "schema": {
                           "$ref": "#/components/schemas/Empty"
                        }
                     }
                  }
               }
            }
         }
      }
   },
   "x-amazon-apigateway-documentation": {
      "version": "1.0.3",
      "documentationParts": [
         {
            "location": {
               "type": "API"
            },
            "properties": {
               "description": "API description",
               "info": {
                  "description": "API info description 4",
                  "version": "API info version 3"
               }
            }
         },
         {
            "location": {
               "type": "METHOD",
               "method": "GET"
            },
            "properties": {
               "description": "Method description."
            }
         },
         {
            "location": {
               "type": "MODEL",
               "name": "Empty"
            },
            "properties": {
               "title": "Empty Schema"
            }
         },
         {
            "location": {
               "type": "RESPONSE",
               "method": "GET",
               "statusCode": "200"
            },
            "properties": {
               "description": "200 response"
            }
         }
      ]
   },
   "servers": [
      {
         "url": "/"
      }
   ],
   "components": {
      "schemas": {
         "Empty": {
            "type": "object",
            "title": "Empty Schema"
         }
      }
   }
}

OpenAPI 2.0

PUT /restapis/<restapi_id>/documentation/parts&mode=overwrite&failonwarnings=true
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

{
  "swagger": "2.0",
  "info": {
    "description": "description",
    "version": "1",
    "title": "doc"
  },
  "host": "",
  "basePath": "/",
  "schemes": [
    "https"
  ],
  "paths": {
    "/": {
      "get": {
        "description": "Method description.",
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "200 response",
            "schema": {
              "$ref": "#/definitions/Empty"
            }
          }
        }
      }
    }
  },
  "definitions": {
    "Empty": {
      "type": "object",
      "title": "Empty Schema"
    }
  },
  "x-amazon-apigateway-documentation": {
    "version": "1.0.3",
    "documentationParts": [
      {
        "location": {
          "type": "API"
        },
        "properties": {
          "description": "API description",
          "info": {
            "description": "API info description 4",
            "version": "API info version 3"
          }
        }
      },
      {
        "location": {
          "type": "METHOD",
          "method": "GET"
        },
        "properties": {
          "description": "Method description."
        }
      },
      {
        "location": {
          "type": "MODEL",
          "name": "Empty"
        },
        "properties": {
          "title": "Empty Schema"
        }
      },
      {
        "location": {
          "type": "RESPONSE",
          "method": "GET",
          "statusCode": "200"
        },
        "properties": {
          "description": "200 response"
        }
      }
    ]
  }
}

Bei Erfolg gibt diese Anforderung eine "200 OK"-Antwort zurück, die die importierte DocumentationPartId in der Nutzlast enthält.

{
  "ids": [
    "kg3mth",
    "796rtf",
    "zhek4p",
    "5ukm9s"
  ]
}

Sie können auch restapi:import oder restapi:put aufrufen. Die Dokumentationsbausteine im Objekt x-amazon-apigateway-documentation werden dann als Teil der OpenAPI-Eingabedatei der API-Definition bereitgestellt. Um die Dokumentationsbausteine vom API-Import auszuschließen, konfigurieren Sie ignore=documentation in den Abfrageparametern der Anforderung.

Importieren der Dokumentationsbausteine mit der API Gateway-Konsole

In den folgenden Anweisungen wird beschrieben, wie Sie Dokumentationsbausteine importieren.

So verwenden Sie die Konsole, um Dokumentationsbausteine einer API aus einer externen Datei zu importieren

1. Wählen Sie Documentation für die API im Hauptnavigationsbereich der Konsole.

2. Wählen Sie Import Documentation im Bereich Documentation.

3. Wählen Sie Select OpenAPI File aus, um eine Datei von einem Laufwerk zu laden, oder kopieren Sie die Inhalte einer Datei in die Dateiansicht. Ein Beispiel finden Sie in der Nutzlast der Beispielanforderung unter Importieren der Dokumentationsbausteine mit der API Gateway-REST-API.

4. Wählen Sie optional Fail on warnings oder Ignore warnings und wählen Sie Merge oder Overwrite in Import mode.

5. Wählen Sie Import.