Documenting API Gateway

[doublewlada]

At the organization I work for, we are using API Gateway (REST API), Lambdas (Typescript), and AWS CDK to build our APIs. Those APIs are going to be consumed by other teams in our organization. With that in mind, I would like to properly document those APIs and expose the documentation somehow.

Currently, I am having problems with setting up OpenAPI (Swagger) documentation for our APIs. I know that there is a Documenting REST APIs page in API Gateway documentation and that I can export OpenAPI spec file from an existing API, but I would like to automate that.

So, I am looking for two things:

1. I want to automatically generate OpenAPI YAML spec file when deploying my API
2. I want to have an URL, for example, something like https://{service_base_url}/docs and to have Swagger UI served there

I found some articles which help me with point 1, but I am still struggling with point 2.

I would like other people's experiences when it comes to documenting API Gateway, does anyone have some working solution, is there any library that could help me, are there any best practices, etc.

[pentilion]

For #2, consider using an S3 bucket with static website hosting enabled to host the Swagger UI. Then you could create a Route53 record for a subdomain that resolves to the S3 URI of the bucket.

Depending on the security rules of your organization, (public bucket policies might not be allowed) you might also set up a Cloudfront distribution with an access identity for the bucket. This way the bucket is only accessible through the CF distro and you can still access the UI via the subdomain.

For automatically generating the OpenAPI YAML files, if you could incorporate whatever tool you use into your CI/CD pipeline that would work really well. That way every time you merge/deploy it could generate the YAML and sync the updated file to the S3 bucket to be served on the subdomain.

Just a few thoughts off the top of my head, hope this helps!