OAS API Explorer

A user interface to explore OpenApi specifications (OAS) with support for OAUTH2 via Auth0.com. For example:

Installation

npm install

Configuration

Copy settings/000-default.json to settings/001-custom.json and replace all configuration values starting with ${APX_..} — to fully understand each field consult #authorize-application. Please note, that multiple configuration files will be merged in lexicographical order.

Auth0: authentication & authorization

"auth0": {

your unique ID of the target API you want to access:

    "api_identifier": "${APX_AUTH0_AUDIENCE}", // e.g. "https://api.custom.tld/"

your application's ID:

    "client_id": "${APX_AUTH0_CLIENT_ID}", // e.g. "00000000...00000000"

your Auth0 domain:

    "domain": "${APX_AUTH0_DOMAIN}", // e.g. "custom.auth0.com"

silent (none) or explicit (login) authentication:

    "prompt": "login",

scopes which you want to request authorization for:

    "scopes": [
        // e.g. "a:scope", "another:scope", "yet-another:scope"
        "openid", "profile", "offline_access", "${APX_API_SCOPES}"
    ],

URL to which Auth0 will redirect to:

    "redirect_uri": "file:///callback"

}

OAS: OpenApi specification

"oas": {

list of allowed API servers (with regex support):

    "servers": [
        // e.g. "^https://(.+)\\.custom\\.tld"
        "${APX_OAS_SERVERS}"
    ],

URL to fetch the default OpenApi specification from:

    // e.g. "https://api.custom.tld/oas/openapi@latest.yaml"
    "url": "${APX_OAS_URL}"

}

Packaging

npm run make

Execution

debugging:

npm start

production:

./api-explorer

CLI Arguments

It's also possible to provide a configuration file and/or arguments via the command line interface. Further, environment variables are also recognized (where the values need to be JSON encoded). The precedence order is given as:

• CLI arguments, then
• environment variables, and finally
• configuration files,

where the CLI arguments have the highest precedence, while the configuration files have the least.

debugging:

APX_AUTH0_PROMPT='"login"' npm run -- start -- --json ./settings/001-custom.json

production:

APX_AUTH0_PROMPT='"login"' ./api-explorer --json ./resources/app/settings/001-custom.json

where the location of the *.json configuration can be anywhere, and is not just restricted to the path shown above, and further where each (even nested) configuration entry can be separately defined as well, for example:

debugging:

npm run -- start -- --json ./settings/001-custom.json \
    --auth0.scopes=openid profile offline_access \
    --auth0.scopes=get:my-scope post:my-scope \
    --oas.servers="^https://(.+).custom.tld" \
    --oas.servers="^http://localhost:8000"

production:

./api-explorer --json ./resources/app/settings/001-custom.json \
    --auth0.scopes=openid profile offline_access \
    --auth0.scopes=get:my-scope post:my-scope \
    --oas.servers="^https://(.+).custom.tld" \
    --oas.servers="^http://localhost:8000"

FAQ

Why do I get an invalid token error?

This might be due to a left-over (access) token, which has not been removed correctly. Simply delete the corresponding AUTH0_DOMAIN folder in your temporary directory, e.g. on Linux for AUTH0_DOMAIN = custom.auth0.com run:

rm /tmp/custom.auth0.com/ -r