@zalando/zally-web-ui

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

Contents

• Requirements
• Install
• Usage
  • Basic
  • Mount to an existing application
  • Configuration options
    • Options
  • Add Authentication
    • POST /auth/me
    • GET /auth/login
    • GET /auth/logout
    • POST /auth/refresh-token (optional)
• Development
  • Install, build and run in development mode
  • Run in production mode
  • Build optimized client javascript bundle
• Contributing
  • Contact
  • License

Requirements

• NodeJS >= 7.6

Install

npm install zally-web-ui --save

or

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

1. 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
2. Publish the new version after the pull request is merged (npm login && npm publish --access=public)

Contributing

People interested contributing to the web-ui project can open issues and related pull requests.

Before opening PRs, be sure the test are running by executing yarn test.

Contact

Feel free to contact one the maintainers

License

MIT license with an exception. See license file.