##TOP## Download Swagger From Api Gateway
Doreen Mammen
TL;DR;
I am keeping my OLD gateway in order to generate swagger.json, but will not deploy it any more to server. I am also creating new OCELOT gateway that will just use that generated swagger.json. Visit Git repository -bojan/ocelot-with-swagger that contains code and build definition for this transition.
I added some sample call from Gateway to Api, so you can verify it works. I commented it out in code so we can prove later we do not need it really, but you can uncomment to see it works. Of course, this is super-simplified code, for easier understanding. Grab a look at the WeatherForecastController.
OK, that works. We have return type, we can add more annotations, so Swagger definition can be more rich, with samples etc. On start it generates swagger.json and all is good. All except I use some Ocelot-like library I made, that is proven in Production, but doesn't have all features Ocelot has and it is not battle tested with hundreds of projects, so some edge cases could occur. In Production. Not so fun.
I deliberately added a dummy.txt file in wwwroot as I had issue with build on Azure DevOps - as nothing was in that folder, it was not created, so saving swagger.json from Test case was failing. Now it is all good.
When using the Try it out button from swagger, if I get back a 200, this is handled perfectly and the result shows as expected. I am trying to get the error codes to display and this is where I am stuck.
There is an Export option that can export documentation as Swagger or OpenAPI3. This will create .json or .yaml file and then consumer has to import these files into swagger UI. However this is not user-friendly option to provide swagger file every time i update documentation to all consumers.
I was wondering, after publishing the documentation is there anyway consumer can access documentation directly via http. So lets assume my dev stage api URL is so something like should launch Swagger UI with latest published swagger file.
Update 1
In ASP.NET Web API or .NET Core you can include Swashbuckle that creates swagger files and also has embedded version of the Swagger UI tool. So after deploying API user can access documentation directly from UI something like
I was hoping the same thing from AWS gateway. After publishing the documentation it should make that documentation available via some predefined resource path.
AWS API Gateway can only make documentation exportable but won't render a UI app. There is no endpoint that you can use in the gateway to render the documentation. You may wish to use third party tools or AWS API Gateway Developer Portal to allow users browse API documentation. You may find this blog helpful.
It'll use the instance's IAM role to download the Swagger spec from API Gateway. Your CI/CD pipeline can restart/refresh Micro Swagger whenever it deploys. Your customers can see the latest API docs at the instance's domain.
In the last post I showed how AWS CDK can be used as a welcome alternative to YAML for describing your cloud infrastructure. Working on my CDK project from I encountered a problem handling Swagger files. But first I want to explain what the Swagger definitions are. It should also be said that the new version of Swagger has been called OpenApi since 2018. When using AWS API Gateway, it is convenient to use Swagger for parameter validation such as Query, Path and Body Parameter. What exactly Swagger is and why I think it's so great I describe in the next section.
Another very powerful feature is that it is possible to generate client libaries from the Swagger definition ( -codegen/). For example, Alfresco does this with the API Explorer (For more information, see GitHub Api-Explorer) and ADF (or ADF JS Github). There, for example, the Swagger File becomes the JavaScript API Library generated, which can be used as a wrapper for the API requests and is also in ADF Components Github.
All the features from the previous section sound very tempting, don't they? How nice that AWS API Gateway also offers to extract Swagger definitions from its deployments and also to import it using CloudFormation or CDK. Unfortunately in connection with AWS CDK, extracted Swagger files are not so easy to reuse for their description. The biggest problem is that if, for example, a lambda is updated, its ARN also changes. However, the Swagger Files extracted from the API Gateway use exactly these ARNs when Lambda is used as a backend implementation for an endpoint. And since the ARN changes, they are outdated in the swagger file. Below is a Swagger Snippet and there you can see the Arn I'm talking about behind the uri keyword.
To solved the problem with deploying CDK twice. The first deploy does not use a swagger definition but the second does. It is really interesting how I generated the Swagger file. In the following I try to describe the process, but please also look into my GitHub repo (there in .travis) for how I implemented this workaround.
Swagger Definitions are ideal for creating, editing, documenting and testing APIs such as those from AWS Api Gateway. They are not only useful directly in the backend. As well they are suited in the frontend because Swagger can generate amazing looking and useful Swagger UI to understand the backend better in a way shorter time.
I love to work on Content Management Open Source projects. A lot from my stuff you can already use on www.github.com/mmuller88 . If you like my work there and my blog posts, please consider supporting me on Patreon:
Answering some of my own questions here - I seems that we will need to use the DB to store the definitions. Long term, this makes sense for our purposes. I am still concerned about how the swagger definitions are imported, as it seems they need to be JSON and be escaped, as indicated here: -apis/#import-dashboard
Important: To use this snippet, replace arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:12345678910:function:mylambda/invocations with the ARN of a Lambda function in the destination account.
4. Under Import from Swagger or Open API 3, do either of the following:
Choose Select Swagger File, then choose your updated OpenAPI definition file.
-or-
Paste your updated OpenAPI definition into the text editor field.
For example, the API Gateway extensions allow you to configure yourendpoint as a Proxy to a particular HTTP endpoint directly in your Swaggerdefinition. In our case, we can forward any requests to received by APIGateway to a backend service that implements the Player API by using thex-amazon-apigateway-integration property.
In order to try out the API using the API Gateway swagger interface, an access token needs to be provided in the Token textbox in the left panel. If you don't have an access token, refer to the previous section Obtaining Access Token
After making a successful call to Refresh Token API, the existing access token which was refreshed will be invalid. You need to use the access token received as a response for this request. You can also obtain this token at later point of time by downloading it from API Gateway.
Swagger configuration on API gateway is not as simple as you are configure normal application. You have to configure it in different way. In this article I will create an API gateway using ocelot and asp.net core application and show you how to configure swagger on API gateway.
If you define enum types with non default value such as declaring 0 value with UNKNOWN and want to omit the default value from generated swagger file, use omit_enum_default_value. This option also applies if enums_as_ints option is enalbled to generate enums as integer.
If you require internal or unreleased fields and APIs to be hidden from your API documentation, google.api.VisibilityRule annotations can be added to customize where they are generated. Combined with the option visibility_restriction_selectors, overlapping rules will appear in the OpenAPI output.
NOTE: These annotations do not alter the behaviour of the gateway and must be coupled with custom header parsing behaviour in the application. Also be aware that adding header parameters can alter the forwards and backwards compatibility of the schema. You must also set a type for your header which can be one of STRING, INTEGER, NUMBER or BOOLEAN.
If you want to remove internal comments from the from OpenAPI output (such as TODO and FIXME directives) you can use the remove_internal_comments option. If set to true, this will remove all comment text located between (-- and --) as per AIP 192: Internal comments.
df19127ead