From da80b49bc588ff0eb6cd1d7fb3dbae5a9cf50a1d Mon Sep 17 00:00:00 2001 From: fahernandez Date: Thu, 14 Feb 2019 16:08:32 -0600 Subject: [PATCH 1/4] 868 improving README with AWS API gateway findings --- README.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/README.md b/README.md index a780964be08..7a9b6ca21f6 100644 --- a/README.md +++ b/README.md @@ -210,6 +210,15 @@ More examples are available under `examples` directory. To use the same port for custom HTTP handlers (e.g. serving `swagger.json`), gRPC-gateway, and a gRPC server, see [this code example by CoreOS](https://github.com/philips/grpc-gateway-example/blob/master/cmd/serve.go) (and its accompanying [blog post](https://coreos.com/blog/gRPC-protobufs-swagger.html)) +## Import swagger documentation into AWS API Gateway +AWS Api gateway service allows to import swagger documentation to create REST API. The process is very straigh foward and can be found [here](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-import-api.html). +These are some considerations when importing the documentation: + +1. Remove model circular dependencies(Circular dependencies 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 is reviewed by the parser but the errors aren't self-explanatory. Review the [documentation](https://swagger.io/specification/v2/) to verify that the requirements are met. +4. API gateway errors aren't good enough for troubleshooting so I recommend using this [page](https://apidevtools.org/swagger-parser/online/) for structure validation. + ## Features ### Supported * Generating JSON API handlers From e0148f3cdc17e1dc4b339874f39e4ac078dfb80a Mon Sep 17 00:00:00 2001 From: fahernandez Date: Fri, 15 Feb 2019 17:06:42 -0600 Subject: [PATCH 2/4] 868 adding review feedback --- README.md | 9 --------- docs/_docs/aws.md | 14 ++++++++++++++ docs/index.md | 1 + 3 files changed, 15 insertions(+), 9 deletions(-) create mode 100644 docs/_docs/aws.md diff --git a/README.md b/README.md index 7a9b6ca21f6..a780964be08 100644 --- a/README.md +++ b/README.md @@ -210,15 +210,6 @@ More examples are available under `examples` directory. To use the same port for custom HTTP handlers (e.g. serving `swagger.json`), gRPC-gateway, and a gRPC server, see [this code example by CoreOS](https://github.com/philips/grpc-gateway-example/blob/master/cmd/serve.go) (and its accompanying [blog post](https://coreos.com/blog/gRPC-protobufs-swagger.html)) -## Import swagger documentation into AWS API Gateway -AWS Api gateway service allows to import swagger documentation to create REST API. The process is very straigh foward and can be found [here](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-import-api.html). -These are some considerations when importing the documentation: - -1. Remove model circular dependencies(Circular dependencies 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 is reviewed by the parser but the errors aren't self-explanatory. Review the [documentation](https://swagger.io/specification/v2/) to verify that the requirements are met. -4. API gateway errors aren't good enough for troubleshooting so I recommend using this [page](https://apidevtools.org/swagger-parser/online/) for structure validation. - ## Features ### Supported * Generating JSON API handlers diff --git a/docs/_docs/aws.md b/docs/_docs/aws.md new file mode 100644 index 00000000000..ec7645a80e5 --- /dev/null +++ b/docs/_docs/aws.md @@ -0,0 +1,14 @@ +--- +category: documentation +--- + +# AWS + +## Import swagger documentation into AWS API Gateway +AWS Api gateway service allows to import swagger documentation to create REST API. The process is very straigh foward and can be found [here](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-import-api.html). +These are some considerations when importing the documentation: + +1. Remove model circular dependencies(Circular dependencies 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 is reviewed by the parser but the errors aren't self-explanatory. Review the [documentation](https://swagger.io/specification/v2/) to verify that the requirements are met. +4. API gateway errors aren't good enough for troubleshooting so I recommend using this [page](https://apidevtools.org/swagger-parser/online/) for structure validation. diff --git a/docs/index.md b/docs/index.md index 59e3047c87a..8b3bbc9f023 100644 --- 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](_docs/aws.md) # Contribution From 552a6c003065480ff7ea6c176308f25506877703 Mon Sep 17 00:00:00 2001 From: fahernandez Date: Fri, 15 Feb 2019 18:31:38 -0600 Subject: [PATCH 3/4] 868 fixing typos related to aws documentation tips --- docs/_docs/aws.md | 10 +++++----- docs/index.md | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/_docs/aws.md b/docs/_docs/aws.md index ec7645a80e5..caa407d4692 100644 --- a/docs/_docs/aws.md +++ b/docs/_docs/aws.md @@ -5,10 +5,10 @@ category: documentation # AWS ## Import swagger documentation into AWS API Gateway -AWS Api gateway service allows to import swagger documentation to create REST API. The process is very straigh foward and can be found [here](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-import-api.html). -These are some considerations when importing the documentation: +The AWS API gateway service allows importing of a 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 model circular dependencies(Circular dependencies aren't supported by the parser). +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 is reviewed by the parser but the errors aren't self-explanatory. Review the [documentation](https://swagger.io/specification/v2/) to verify that the requirements are met. -4. API gateway errors aren't good enough for troubleshooting so I recommend using this [page](https://apidevtools.org/swagger-parser/online/) for structure validation. +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 index 8b3bbc9f023..57b23e1add0 100644 --- a/docs/index.md +++ b/docs/index.md @@ -17,7 +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](_docs/aws.md) +* [AWS API Gateway tips](_docs/aws.md) # Contribution From ccda42b557f11755c4726fb4a2428395cdcac485 Mon Sep 17 00:00:00 2001 From: Johan Brandhorst Date: Mon, 18 Feb 2019 09:41:23 -0600 Subject: [PATCH 4/4] Update docs/_docs/aws.md Co-Authored-By: fahernandez --- docs/_docs/aws.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_docs/aws.md b/docs/_docs/aws.md index caa407d4692..96e98c089b6 100644 --- a/docs/_docs/aws.md +++ b/docs/_docs/aws.md @@ -5,7 +5,7 @@ category: documentation # AWS ## Import swagger documentation into AWS API Gateway -The AWS API gateway service allows importing of a 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). +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).