Arbeiten mit OpenAPI-Definitionen für HTTP-APIs

Sie können Ihre HTTP-API definieren, indem Sie eine OpenAPI 3.0-Definitionsdatei verwenden. Anschließend können Sie die Definition in API Gateway importieren, um eine API zu erstellen. Weitere Informationen zu API Gateway-Erweiterungen für OpenAPI finden Sie unter API Gateway-Erweiterungen für OpenAPI arbeiten.

Importieren einer HTTP-API

Sie können eine HTTP-API erstellen, indem Sie eine OpenAPI 3.0-Definitionsdatei importieren.

Um von einer REST-API zu einer HTTP-API zu migrieren, können Sie Ihre REST-API als OpenAPI 3.0-Definitionsdatei exportieren. Importieren Sie dann die API-Definition als HTTP-API. Weitere Informationen zum Exportieren einer REST-API finden Sie unter REST-API von API Gateway importieren.

Anmerkung

HTTP-APIs unterstützen dieselben AWS Variablen wie REST-APIs. Weitere Informationen hierzu finden Sie unter AWS Variablen für den OpenAPI-Import.

Importieren von Validierungsinformationen

Beim Importieren einer API stellt API Gateway drei Kategorien von Validierungsinformationen bereit.

Informationen

Eine Eigenschaft ist gemäß der OpenAPI-Spezifikation gültig, diese Eigenschaft wird für HTTP-APIs jedoch nicht unterstützt.

Beispielsweise erzeugt das folgende OpenAPI 3.0-Snippet Informationen zum Import, da HTTP-APIs die Anfragevalidierung nicht unterstützen. API Gateway ignoriert die Felder requestBody und schema.

"paths": {
  "/": {
    "get": {
      "x-amazon-apigateway-integration": {
        "type": "AWS_PROXY",
        "httpMethod": "POST",
        "uri": "arn:aws:lambda:us-east-2:123456789012:function:HelloWorld",
        "payloadFormatVersion": "1.0"
      },
      "requestBody": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Body"
            }
          }
        }
      }
    }
  }
  ...
},
"components": {
  "schemas": {
    "Body": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string"
        }
      }
    }
    ...
  }
  ...
}

Warnung

Eine Eigenschaft oder Struktur ist gemäß der OpenAPI-Spezifikation ungültig, blockiert die API-Erstellung jedoch nicht. Sie können angeben, ob API Gateway diese Warnungen ignorieren und mit der API-Erstellung fortfahren oder die API-Erstellung bei Warnungen beenden soll.

Das folgende OpenAPI 3.0-Dokument erzeugt Warnungen beim Import, da HTTP-APIs nur Lambda-Proxy- und HTTP-Proxy-Integrationen unterstützen.

"x-amazon-apigateway-integration": {
  "type": "AWS",
  "httpMethod": "POST",
  "uri": "arn:aws:lambda:us-east-2:123456789012:function:HelloWorld",
  "payloadFormatVersion": "1.0"
}

Fehler

Die OpenAPI-Spezifikation ist ungültig oder fehlerhaft. API Gateway kann keine Ressourcen aus dem fehlerhaften Dokument erstellen. Sie müssen die Fehler beheben und es anschließend erneut versuchen.

Die folgende API-Definition erzeugt Fehler beim Import, da HTTP-APIs nur die OpenAPI 3.0-Spezifikation unterstützen.

{
  "swagger": "2.0.0",
  "info": {
    "title": "My API",
    "description": "An Example OpenAPI definition for Errors/Warnings/ImportInfo",
    "version": "1.0"
  }
  ...
}

Ein weiteres Beispiel: Während OpenAPI es Benutzern ermöglicht, eine API mit mehreren Sicherheitsanforderungen zu definieren, die mit einer bestimmten Operation verbunden sind, wird dies von API Gateway nicht unterstützt. Jede Operation kann nur eine IAM-Autorisierung, einen Lambda-Genehmiger oder einen JWT-Genehmiger haben. Der Versuch, mehrere Sicherheitsanforderungen zu modellieren, führt zu einem Fehler.

Importieren Sie eine API mit dem AWS CLI

Der folgende Befehl importiert die OpenAPI 3.0-Definitionsdatei api-definition.json als HTTP-API.

aws apigatewayv2 import-api --body file://api-definition.json

Sie können das folgende Beispiel einer OpenAPI 3.0-Definition importieren, um eine HTTP-API zu erstellen.

{
  "openapi": "3.0.1",
  "info": {
    "title": "Example Pet Store",
    "description": "A Pet Store API.",
    "version": "1.0"
  },
  "paths": {
    "/pets": {
      "get": {
        "operationId": "GET HTTP",
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200 response",
            "headers": {
              "Access-Control-Allow-Origin": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Pets"
                }
              }
            }
          }
        },
        "x-amazon-apigateway-integration": {
          "type": "HTTP_PROXY",
          "httpMethod": "GET",
          "uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets",
          "payloadFormatVersion": 1.0
        }
      },
      "post": {
        "operationId": "Create Pet",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NewPet"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "200 response",
            "headers": {
              "Access-Control-Allow-Origin": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NewPetResponse"
                }
              }
            }
          }
        },
        "x-amazon-apigateway-integration": {
          "type": "HTTP_PROXY",
          "httpMethod": "POST",
          "uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets",
          "payloadFormatVersion": 1.0
        }
      }
    },
    "/pets/{petId}": {
      "get": {
        "operationId": "Get Pet",
        "parameters": [
          {
            "name": "petId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200 response",
            "headers": {
              "Access-Control-Allow-Origin": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Pet"
                }
              }
            }
          }
        },        
        "x-amazon-apigateway-integration": {
          "type": "HTTP_PROXY",
          "httpMethod": "GET",
          "uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets/{petId}",
          "payloadFormatVersion": 1.0
        }
      }
    }
  },
  "x-amazon-apigateway-cors": {
    "allowOrigins": [
      "*"
    ],
    "allowMethods": [
      "GET",
      "OPTIONS",
      "POST"
    ],
    "allowHeaders": [
      "x-amzm-header",
      "x-apigateway-header",
      "x-api-key",
      "authorization",
      "x-amz-date",
      "content-type"
    ]
  },
  "components": {
    "schemas": {
      "Pets": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/Pet"
        }
      },
      "Empty": {
        "type": "object"
      },
      "NewPetResponse": {
        "type": "object",
        "properties": {
          "pet": {
            "$ref": "#/components/schemas/Pet"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "Pet": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "price": {
            "type": "number"
          }
        }
      },
      "NewPet": {
        "type": "object",
        "properties": {
          "type": {
            "$ref": "#/components/schemas/PetType"
          },
          "price": {
            "type": "number"
          }
        }
      },
      "PetType": {
        "type": "string",
        "enum": [
          "dog",
          "cat",
          "fish",
          "bird",
          "gecko"
        ]
      }
    }
  }
}