22

I have created API using AWS Api Gateway. Then i have documented documentation parts for all the entities ( like API, RESOURCE, METHOD, MODEL etc). Then using AWS Gateway Console i have published the documentation to dev stage with version 1

But i am not sure how do i (or the consumer of the API) going to access the documentation?

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 https://devapi.example.com/v1 so something like https://devapi.example.com/v1/help 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 https://devapi.example.com/swagger.
I was hoping the same thing from AWS gateway. After publishing the documentation it should make that documentation available via some predefined resource path.

LP13
  • 30,567
  • 53
  • 217
  • 400
  • 2
    I thought this is genuine question. I couldn't find any information in AWS. care to explain why down-voted this question? – LP13 Jan 15 '19 at 23:27
  • If API Gateway conforms to OpenAPI 3 "should" clause on file locations, you might try `openapi.json` or `openapi.yaml`. – bishop Jan 15 '19 at 23:44
  • My be i didnt ask my question right. I wanted to know if AWS API Gateway can show documentation using Swagger UI? out of the box – LP13 Jan 16 '19 at 16:40

2 Answers2

6

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.

A.Khan
  • 3,826
  • 21
  • 25
-6

Micro Swagger imports swagger spec from Amazon API Gateway & serves a swagger UI from it.

You can leave it running on an EC2 instance:

npm i -g micro-swagger
micro-swagger start

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.

Harish KM
  • 1,303
  • 7
  • 17
Nir Adler
  • 11
  • 5
  • 3
    While this may solve the problem, it doesn't explain why or how it answers the question. Please [include an explanation](//meta.stackexchange.com/q/114762/269535), as that really helps to improve the quality of your post. Remember that you are answering the question for readers in the future, and those people might not know the reasons for your suggestion. – Samuel Philipp Apr 30 '19 at 21:39
  • @SamuelPhilipp, I've updated the answer to include an explanation. – Harish KM Jan 19 '21 at 12:41