868 improving README with AWS API gateway findings (#869)

* 868 improving README with AWS API gateway findings * 868 adding review feedback * 868 fixing typos related to aws documentation tips * Update docs/_docs/aws.md Co-Authored-By: fahernandez <fabian.hernandez@hulihealth.com>
grpc-ecosystem · Feb 18, 2019 · ada3454 · ada3454
1 parent 8ce214f
commit ada3454
Show file tree

Hide file tree

Showing 2 changed files with 15 additions and 0 deletions.
diff --git a/docs/_docs/aws.md b/docs/_docs/aws.md
@@ -0,0 +1,14 @@
+---
+category: documentation
+---
+
+# AWS
+
+## Import swagger documentation into AWS API Gateway
+The AWS API gateway service allows importing of an OpenAPI specification to create a REST API. The process is very straightforward and can be found [here](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-import-api.html).
+Here are some tips to consider when importing the documentation:
+
+1. Remove any circular dependencies (these aren't supported by the parser).
+2. Remove security-related annotations (These annotations aren't well supported by the parser).
+3. Max length of fields are reviewed by the parser but the errors aren't self-explanatory. Review the [specification](https://swagger.io/specification/v2/) to verify that the requirements are met.
+4. API gateway errors aren't great, but you can use this [page](https://apidevtools.org/swagger-parser/online/) for structure validation.
diff --git a/docs/index.md b/docs/index.md
@@ -17,6 +17,7 @@ To learn more about us check out our documentation on:
 *   [Installation and usage](_docs/usage.md)
 *   [Examples](_docs/examples.md)
 *   [Features](_docs/features.md)
+*   [AWS API Gateway tips](_docs/aws.md)
 
 
 # Contribution