zally

A customized fork from Zalando's awesome Zally. It enforces some automatically checkable rules from SBB's API Principles.

View the Project on GitHub SchweizerischeBundesbahnen/zally

dependencies Status codecov

Zally WEB-UI

The project provides a simple web user interface client for Zally Server, a tool to lint your OpenAPI specs.

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

Main features

Contents

Requirements

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

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.