Command line tool for generating OpenAPI spec and SwaggerUI from AWS API Gateway
$ npx apig-swagger-ui -r ap-southeast-2 -s npx: installed 92 in 9.635s Generating files to: api-doc Generating OpenAPI spec for: https://api.dev1.insights.example.com/analytics Generating OpenAPI spec for: https://boi.example.com/statement Generating OpenAPI spec for: https://catalog.tst1.example.com/ Generating OpenAPI spec for: https://cis.example.com/ Generating OpenAPI spec for: https://leads.example.com/v2 Generating OpenAPI spec for: https://leads.example.com/inbound Generating OpenAPI spec for: https://rulehub.example.com/citizenship Generating OpenAPI spec for: https://toggle-feature-flag-datadog.example.com/ Generating OpenAPI spec for: https://v1pde.example.com/key Local server started. Ctrl-C to stop. Access URL: http://localhost:8001/
Command line option
-r ap-southeast-2 specifies AWS region,
-s tells the command line to start up a local http server and then open the browser pointing to that local server for viewing generated website.
If you don't want to include all custom domains and APIs,
you can use
--exclude options to specify which domain/path to include and which to exclude.
Both of them can have multiple appearances.
--include 'leads*/*' will make sure that only
https://leads.example.com/inbound would be included.
Make sure you have the pattern enclosed with
--include is applied before
--exclude, so that
--include 'leads*/*' --exclude '*/v2' will give you only
To match an endpoint URL without a base path, use patterns like
*.example.*/ which matches
Please note that
*.example.*/* does not match
This applies to both inclusion and exclusion.
Necessary transformation/hacking is in place for making sure API spec looks good in Swagger UI. Feel free to let me know if you have any suggestions or needs, I would consider to add as new features.
Files generated are ready to be hosted as static website content in this structure:
api/- folder containing all OpenAPI 3 spec files
<domain>/- folder containing OpenAPI 3 spec files under the same API Gateway custom domain name
<basePath>.apig.json- original OpenAPI 3 spec file exported from API Gateway
<basePath>.json- OpenAPI 3 spec file for SwaggerUI to consume. Necessary transformation/hacking has been applied for making sure the API spec looks good in Swagger UI.
swagger-ui/- standard swagger-ui html/js/css/png
index.html- the home page / entry point
You can have it installed globally like this:
$ npm install -g apig-swagger-ui $ apig-swagger-ui ... ...
Or, you can just invoke the latest version with
$ npx apig-swagger-ui ... ...
--help to the command line, you can see all supported arguments and options.
USAGE $ apig-swagger-ui [PATH] ARGUMENTS PATH [default: api-doc] path for putting generated website files OPTIONS -a, --validator-url=validator-url custom validator URL, or "none" for disabling validation -d, --debug output debug messages -h, --help show CLI help -i, --include=include [default: */*,*/] custom domains and base path mappings to include -m, --enable-source-maps include swagger-ui's source map files or not -p, --port=port [default: 8001] port number of the local http server for preview -q, --quiet no console output -r, --region=region AWS region -s, --server start a local http server and open a browser for pre-viewing generated website -v, --version show CLI version -x, --exclude=exclude custom domains and base path mappings to exclude DESCRIPTION This command line tool can generate a static website that you can host for serving Swagger UI of your API Gateway APIs. It generates website files locally and can optionally launch a local server for you to preview. Before running this tool, you need to log into your AWS account (through command line like aws, saml2aws, okta-aws, etc.) first. Please note that only APIs that have been mapped to custom domains will be included in the website generated. EXAMPLES apig-swagger-ui -r ap-southeast-2 -s apig-swagger-ui -r ap-southeast-2 -s -i '*uat1*/*' -x 'datahub.uat1.*/*' apig-swagger-ui -r ap-southeast-2 -s -i '*/key*' -i 'boi.stg.*/*' path/to/api-doc/directory
- Run for test:
npm version patch -m "..."; npm publish