diff --git a/aws/resource_aws_api_gateway_rest_api.go b/aws/resource_aws_api_gateway_rest_api.go
index a135d5cf71f..3b555b6b9d7 100644
--- a/aws/resource_aws_api_gateway_rest_api.go
+++ b/aws/resource_aws_api_gateway_rest_api.go
@@ -8,6 +8,7 @@ import (
 	"github.com/aws/aws-sdk-go/aws"
 	"github.com/aws/aws-sdk-go/aws/awserr"
 	"github.com/aws/aws-sdk-go/service/apigateway"
+	"github.com/hashicorp/errwrap"
 	"github.com/hashicorp/terraform/helper/resource"
 	"github.com/hashicorp/terraform/helper/schema"
 )
@@ -82,13 +83,14 @@ func resourceAwsApiGatewayRestApiCreate(d *schema.ResourceData, meta interface{}
 	d.SetId(*gateway.Id)
 
 	if body, ok := d.GetOk("body"); ok {
+		log.Printf("[DEBUG] Initializing API Gateway from OpenAPI spec %s", d.Id())
 		_, err := conn.PutRestApi(&apigateway.PutRestApiInput{
 			RestApiId: gateway.Id,
-			Mode:      aws.String("overwrite"),
+			Mode:      aws.String(apigateway.PutModeOverwrite),
 			Body:      []byte(body.(string)),
 		})
 		if err != nil {
-			return fmt.Errorf("Error putting API Gateway specification: %s", err)
+			return errwrap.Wrapf("Error creating API Gateway specification: {{err}}", err)
 		}
 	}
 
@@ -173,13 +175,14 @@ func resourceAwsApiGatewayRestApiUpdate(d *schema.ResourceData, meta interface{}
 
 	if d.HasChange("body") {
 		if body, ok := d.GetOk("body"); ok {
+			log.Printf("[DEBUG] Updating API Gateway from OpenAPI spec: %s", d.Id())
 			_, err := conn.PutRestApi(&apigateway.PutRestApiInput{
 				RestApiId: aws.String(d.Id()),
-				Mode:      aws.String("overwrite"),
+				Mode:      aws.String(apigateway.PutModeOverwrite),
 				Body:      []byte(body.(string)),
 			})
 			if err != nil {
-				return err
+				return errwrap.Wrapf("Error updating API Gateway specification: {{err}}", err)
 			}
 		}
 	}
diff --git a/aws/resource_aws_api_gateway_rest_api_test.go b/aws/resource_aws_api_gateway_rest_api_test.go
index 82bee930d9f..00be39cc5d2 100644
--- a/aws/resource_aws_api_gateway_rest_api_test.go
+++ b/aws/resource_aws_api_gateway_rest_api_test.go
@@ -222,10 +222,10 @@ resource "aws_api_gateway_rest_api" "test" {
   name = "test"
   body = <<EOF
 {
-	"swagger": "2.0",
-	"info": {
-		"title": "test",
-		"version": "2017-04-20T04:08:08Z"
+  "swagger": "2.0",
+  "info": {
+    "title": "test",
+    "version": "2017-04-20T04:08:08Z"
   },
   "schemes": [
     "https"
@@ -261,10 +261,10 @@ resource "aws_api_gateway_rest_api" "test" {
   name = "test"
   body = <<EOF
 {
-	"swagger": "2.0",
-	"info": {
-		"title": "test",
-		"version": "2017-04-20T04:08:08Z"
+  "swagger": "2.0",
+  "info": {
+    "title": "test",
+    "version": "2017-04-20T04:08:08Z"
   },
   "schemes": [
     "https"
diff --git a/website/docs/r/api_gateway_rest_api.html.markdown b/website/docs/r/api_gateway_rest_api.html.markdown
index 931e95d4b85..23d0e8ac32b 100644
--- a/website/docs/r/api_gateway_rest_api.html.markdown
+++ b/website/docs/r/api_gateway_rest_api.html.markdown
@@ -28,6 +28,17 @@ The following arguments are supported:
 * `binary_media_types` - (Optional) The list of binary media types supported by the RestApi. By default, the RestApi supports only UTF-8-encoded text payloads.
 * `body` - (Optional) An OpenAPI specification that defines the set of routes and integrations to create as part of the REST API.
 
+__Note__: If the `body` argument is provided, the OpenAPI specification will be used to configure the resources, methods and integrations for the Rest API. If this argument is provided, the following resources should not be configured manually for the same REST API, as updates may cause manual resource updates to be overwritten:
+
+* `aws_api_gateway_resource`
+* `aws_api_gateway_method`
+* `aws_api_gateway_method_response`
+* `aws_api_gateway_method_settings`
+* `aws_api_gateway_integration`
+* `aws_api_gateway_integration_response`
+* `aws_api_gateway_gateway_response`
+* `aws_api_gateway_model`
+
 ## Attributes Reference
 
 The following attributes are exported: