@zalando/zally-web-ui NPM

Zally WEB-UI

The project provides a simple web user interface client for Zally Rest API, a tool to lint your api specs.

It's implemented as an express app/middleware and a Single Page Application based on React.

Main features

lint api spec by url or using the built-in yaml/json editor
show active/inactive supported lint rules
optional authentication hooks

Requirements

NodeJS >= 7.6

Install

npm install zally-web-ui --save

yarn add zally-web-ui

Usage

Basic

const app = require('zally-web-ui')();

app.listen(3000, () => {
  console.log('zally-web-ui running at http://localhost:3000');
});

Mount to an existing application

const app = require('express')()
const zally = require('zally-web-ui')(/*options*/);

app.use('/api-linter', zally);
app.listen(3000, () => {
  console.log('server running at http://localhost:3000');
});

Configuration options

When instantiating the app you can pass an options object to customize the behavior.

const options = { /* ..my options.. */}
const zally = require('zally-web-ui')(options);

Options

windowEnv: the windowEnv object contains all the values exposed to the client on window.env
windowEnv.OAUTH_ENABLED (default: false): enable OAuth or just Auth support on the client side (an http call will be fired on /auth/me endpoint to get the current logged in user, if any)
windowEnv.ZALLY_API_URL (default: http://localhost:8080): URL pointing to Zally REST API
windowEnv.DEBUG (default: true): logs debugging message on the client side
logger (default: console): custom logger
handlers: the handlers object contains all route handlers used by zally-web-ui
handlers.assets: handler that serve static assets
handlers.windowEnv: handler that serve /env.js javascript file used to expose windowEnv values to the client on window.env
handlers.index: handler that serve the single page application entrypoint on the wild card * to allow HTML5 History API working as expected

Add Authentication

To add authentication the express server serving zally-web-ui MUST implement some REST API JSON endpoints and set windowEnv.OAUTH_ENABLED to true.

POST /auth/me

Should respond back with 200 http status code and a json response containing the current connected user in this format:

{
  "username": "John Doe",
  "authenticated": true
}

Or with 401 http status code if the user is not connected

GET /auth/login

To show a login or redirect to an external login (if for example you are using some OAuth Provider)

GET /auth/logout

To logout the user (for example clearing the session, etc.)

POST /auth/refresh-token (optional)

Optionally implement this endpoint to refresh an expired token (if for example you are using some OAuth Provider that support this feature)

Development

A Zally Rest Api server MUST be running on your local machine or somewhere over the network. Use windowEnv.ZALLY_API_URL configuration option to set the desired value.

Install, build and run in development mode

yarn
yarn dev

The yarn dev task starts the application server in development mode with nodemon and webpack-dev-server watching for changes. The application server acts as a proxy to webpack-dev-server as the target.

Run in production mode

yarn build
yarn start

Build optimized client javascript bundle

Build webpack bundle minified and source-map file(s).

yarn build

Release it

Create a pull request for the new version (e.g. branchweb-ui-release-1.1)
1. Bump the package version in package.json
2. Add changelog information and adjust documentation
Publish the new version after the pull request is merged (npm login && npm publish --access=public)