npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

apig-swagger-ui

v1.5.1

Published

Command line tool for generating OpenAPI spec and SwaggerUI from AWS API Gateway

Downloads

50

Readme

apig-swagger-ui

Command line tool for generating OpenAPI spec and SwaggerUI from AWS API Gateway

oclif Version Downloads/week License

Typical usage:

$ npx apig-swagger-ui -r ap-southeast-2 -s
npx: installed 92 in 9.635s
Clearing destination folder: 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.

Multiple regions can be specified, in case you want to survey APIs in more than one region.

If you don't want to include all custom domains and APIs, you can use --include and --exclude options to specify which domain/path to include and which to exclude. Both of them can have multiple appearances.

For example, --include 'leads*/*' will make sure that only https://leads.example.com/v2 and 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 https://leads.example.com/inbound.

To match an endpoint URL without a base path, use patterns like *.example.*/ which matches https://cis.example.com/. Please note that *.example.*/* does not match https://cis.example.com/. 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

Quick start

In Node.js environment

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:

$ npx apig-swagger-ui ...
...

By passing -h or --help to the command line, you can see all supported arguments and options.

It can also be used in your own code, like this:

import ApigSwaggerUi from 'apig-swagger-ui';

class Generator extends ApigSwaggerUi {
  argv: string[] = ['api-doc/prod', '-r', 'ap-southeast-2'];
}
await Generator.run();

Install pre-built binary

apig-swagger-ui can be installed through Homebrew (brew install handy-common-utils/tap/apig-swagger-ui for Linux or MacOS), snap (snap install apig-swagger-ui for Linux except WSL), or manual download (https://github.com/james-hu/apig-swagger-ui/releases for Windows, Linux, and MacOS ).

Manual

USAGE
  $ apig-swagger-ui  [PATH] [-v] [-h] [-r <value>] [-k
    <value>] [-e <value>] [-t <value>] [-i <value>] [-x <value>] [-s] [-p
    <value>] [-q] [-d] [-a <value>] [-m]

ARGUMENTS
  PATH  [default: api-doc] path for putting generated website files

FLAGS
  -a, --validator-url=<value>  custom validator URL, or "none" for disabling
                               validation
  -d, --debug                  output debug messages
  -e, --secret=<value>         AWS secret access key
  -h, --help                   Show CLI help.
  -i, --include=<value>...     [default: */*,*/] custom domains and base path
                               mappings to include
  -k, --key=<value>            AWS access key ID
  -m, --enable-source-maps     include swagger-ui's source map files or not
  -p, --port=<value>           [default: 8001] port number of the local http
                               server for preview
  -q, --quiet                  no console output
  -r, --region=<value>...      AWS region
  -s, --server                 start a local http server and open a browser for
                               pre-viewing generated website
  -t, --token=<value>          AWS session token
  -v, --version                Show CLI version.
  -x, --exclude=<value>...     custom domains and base path mappings to exclude

DESCRIPTION
  Command line tool for generating OpenAPI spec and Swagger UI from AWS API
  Gateway

  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 -r us-east-1 -s -i '*uat1*/*' -x 'datahub.uat1.*/*'

  $ apig-swagger-ui -r ap-southeast-2 -s -i '*/key*' -i 'boi.stg.*/*' path/to/api-doc/directory

Contributing

Development:

  • Run for test: ./bin/run ...
  • Release: npm version patch && npm publish && git push --tags

Please ignore main.go and go.mod files. They exist only because we are using goreleaser.

To build binaries for arm64 processors, you need a Linux machine, with binfmt and ldid installed:

  • https://hub.docker.com/r/tonistiigi/binfmt
  • https://stackoverflow.com/a/27769297

To debug goreleaser:

GITHUB_TOKEN=<the-token> goreleaser release --skip-validate --rm-dist --debug