Skip to content

Commit

Permalink
docs: update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@MaethorNaur
MaethorNaur committed Mar 12, 2021
1 parent 9cd1629 commit 9defc3a
Showing 1 changed file with 4 additions and 384 deletions.
388 changes: 4 additions & 384 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,391 +4,11 @@
[![codecov](https://codecov.io/gh/UnisonUI/UnisonUI/branch/master/graph/badge.svg)](https://codecov.io/gh/UnisonUI/UnisonUI)
[![CodeFactor](https://www.codefactor.io/repository/github/unisonui/UnisonUI/badge)](https://www.codefactor.io/repository/github/unisonui/UnisonUI)

RestUI is intended to be a centralised UI for all your **OpenApi Specification** files.
UnisonUI is intended to be a centralised UI for all your **OpenApi Specification** or **gRPC/Protobuf** files.

RestUI is an autonomous server, which discovers your **OpenAPI Spec** for you.
UnisonUI is an autonomous server, which discovers your **OpenAPI Spec** or **gRPC/Protobuf** for you.

Currently, RestUI can discover your API descriptions through `Docker`, `Kubernetes`, `Git`/`Github` or `Webhooks`
Currently, UnisonUI can discover your API descriptions through `Docker`, `Kubernetes`, `Git`/`Github` or `Webhooks`

## Overview

![Screenshot 1](./docs/screenshot-1.png "Screenshot 1")
![Screenshot 2](./docs/screenshot-2.png "Screenshot 2")
![Screenshot 3](./docs/screenshot-3.png "Screenshot 3")

## Build

### Requirements

- JDK 11+
- NodeJS/Npm: Front the React application

### React application

#### There are two ways to build it:

#### 1. Using SBT

```sh
sbt ";project rest-ui; npmInstall; webpackDevTask"
```

`webpackDevTask` can be replaced by `webpackProdTask` if you want to produce minified assets.

#### 2. Using NodeJS

```sh
cd rest-ui
npm install
npm run build
```

`npm run build` can be replaced by `npm run prod` if you want to produce minified assets.

### RestUI

Once the React application is built you can generate the package for RestUI

```sh
sbt "project rest-ui; packageBin"
```

This will produce a zip located: `rest-ui/target/universal/rest-ui-{VERSION}-SNAPSHOT.zip`

You also can use `docker:publishLocal` instead of `packageBin` if you want directly to produce a docker image

## Usage

This project is targeted for Java 11+ in order

### Configuration

RestUI uses a HOCON format for its configuration.

Here is the default configuration used by RestUI.
```hocon
unisonui {
// List of active providers
// By default all available providers are activated
// You can activate the the providers you want by overriding this field
self-specification = no // Should the webhook's specification be available in RestUI
providers = [
"tech.unisonui.providers.git.GitProvider",
"tech.unisonui.providers.docker.DockerProvider",
"tech.unisonui.providers.kubernetes.KubernetesProvider",
"tech.unisonui.providers.webhook.WebhookProvider"
]
http {
port = 8080 // Port of the Webserver
interface = "0.0.0.0" // Interface where the webserver listen to
}
// Configuration for the docker provider
// More information about how this provider works in the Docker provider section
provider.docker {
host = "unix:///var/run/docker.sock" // Docker host
// Labels name use to detect RestUI compatible container
labels {
service-name = "unisonui.service-name" // Label specifying the service name for RestUI.
port = "unisonui.specification.port" // Label specifying the port on which the OpenApi spec is available.
specification-path = "unisonui.specification.path" // Label of the path where the OpenApi spec file is.
use-proxy = "unisonui.specification.use-proxy" // Label uses to enable the usage of the proxy.
grpc-port = "unisonui.grpc.port" // Label specifying the port of the grpc endpoint.
grpc-tls = "unisonui.grpc.tls" // Label specifying the grpc endpoint uses tls (false by default).
}
}
// Configuration for the Kubernetes provider
// More information about how this provider works in the Kubernetes provider section
provider.kubernetes {
polling-interval = "1 minute" // Interval between each polling
labels {
port = "unisonui.specification.port" // Label specifying the port on which the OpenApi spec is available.
protocol = "unisonui.specification.eprotocol" // Label specifying which protocol the OpenApi spec is exposed.
specification-path = "unisonui.specification.path" // Label of the path where the OpenApi spec file is.
use-proxy = "unisonui.specification.use-proxy" // Label use to enable the usage of the proxy.
grpc-port = "unisonui.grpc.port" // Label specifying the port of the grpc endpoint.
grpc-tls = "unisonui.grpc.tls" // Label specifying the grpc endpoint uses tls (false by default).
}
}
// Configuration for the git provider
// More information about how this provider works in the Git provider section
provider.git {
cache-duration = "2 hours" // Interval between each clone....
vcs {
// Specific to Github
github {
api-token = "" // Github personal token.
api-uri = "https://api.github.com/graphql" // Github GraphQL url.
polling-interval = "1 hour" // Interval between each polling.
repositories = [] // List of repositories.
}
git {
repositories = [] // List of repositories
}
}
}
provider.webhook {
interface = "0.0.0.0" // Interface where the webhook server listen to
port = 3000 // Port used by the webhook server
self-specification = no // Should the webhook's specification be available in RestUI
}
}
```

To override the default values you can either create your configuration file
_(with only the fields you want to override)_, or pass parameter fields through system properties:

It is also possible to combine the configuration file and system properties at the time, but
in that case, the system properties values will **prevail**.

Example:

1. Pass a configuration file to system properties
```sh
rest-ui my-config.conf
```
2. Pass parameter fields and override the values to system properties:
```sh
rest-ui -Dunisonui.providers.0=Provider1, -Dunisonui.providers.1=Provider2, ...
```

## Providers

### Docker provider

**Warning: the docker provider DOES NOT support TLS connection yet**

The docker provider list and detect all running containers in real time.

A compatible container **MUST** include the following labels:

- A label specifying the service's name `unisonui.service-name`
- A label specifying the port where the OpenApi spec lays `unisonui.specification.port`

Optional labels:

- A label specifying the path where the OpenApi spec lays `unisonui.specification.path`.

Default path: `/specification.yaml`

Example:

```sh
docker run --rm -l "unisonui.port=80" -l "unisonui.service-name=nginx" -v $(pwd):/usr/share/nginx/html:ro nginx:alpine
```

------------------------------------------------------------------------------------------------

### Kubernetes provider

In order to discover **OpenApi Specs** with RestUI in Kubernetes, the service **MUST** run inside the same Kubernetes cluster of your services.

The Kubernetes provider list and detect all running services in real time.

New services are detected by polling from the Kubernetes API at a regular interval.
The value for the interval is defined by `polling-interval` which default to `1 minute`.

A compatible service **MUST** have the following labels on it:

- A label specifying the protocol `unisonui.specification.protocol`
- A label specifying the port where the OpenApi spec lays `unisonui.specification.port`

Optional labels:

- A label specifying the path where the OpenApi spec lays `unisonui.specification.path`.

Default path is: `/specification.yaml`

Also the services **MUST** have a `ClusterIP` (the provider will infer the address from the `ClusterIP`)

Example:

```yaml
apiVersion: v1
kind: Service
metadata:
labels:
unisonui.specification.port: "80"
unisonui.specification.protocol: http
name: specification
namespace: default
spec:
clusterIP: 10.96.0.2
ports:
- name: 80tcp02
port: 80
protocol: TCP
targetPort: 80
selector:
selector: deployment
sessionAffinity: None
type: ClusterIP
status:
loadBalancer: {}
---
apiVersion: apps/v1
kind: Deployment
metadata:
labels:
selector: deployment
name: openapi
namespace: default
spec:
progressDeadlineSeconds: 600
replicas: 1
revisionHistoryLimit: 10
selector:
matchLabels:
selector: deployment
strategy:
rollingUpdate:
maxSurge: 1
maxUnavailable: 0
type: RollingUpdate
template:
metadata:
labels:
selector: deployment
spec:
containers:
- image: nginx:alpine
imagePullPolicy: Always
name: openapi
ports:
- containerPort: 80
name: 80tcp02
protocol: TCP
resources: {}
securityContext:
allowPrivilegeEscalation: false
capabilities: {}
privileged: false
readOnlyRootFilesystem: false
runAsNonRoot: false
stdin: true
terminationMessagePath: /dev/termination-log
terminationMessagePolicy: File
tty: true
dnsPolicy: ClusterFirst
restartPolicy: Always
schedulerName: default-scheduler
securityContext: {}
terminationGracePeriodSeconds: 30
```

------------------------------------------------------------------------------------------------

### Git provider

The git provider can be used to clone git repositories at a regular interval (`cache-duration`).
You can either provide the list of repositories you to clone or use Github to discover repositories.

It's possible to use both options at the same time.

Each option requires a list of `repositories`. This list can be either a **string** corresponding to
the full URL/Regex (`organization/project` for Github) or on an object.

The object follows this schema:

```hocon
{
location = "" // Full url, `organization/project` for Github
// or a regex (the string **MUST** starts and ends with `/`)
branch = "" // Branch to clone (default to `master` or inferred from the default branch in Github)
specification-paths = [] // List of OpenApi spec files or directories containing those kind of files
// inside your repository. Those paths are overrided by the unisonui configuration file inside
// of your repository.
use-proxy = no // Just enable the proxy or not for this repository
}
```

If the repository contains a file at the root level called `.unisonui.yaml` then Git provider will
read the OpenApi spec files specified in that file.

Example:

`.unisonui.yaml`

```yaml
name: "Test"
openapi:
useProxy: false
specifications:
- "foo-service.yaml"
- "/openapi/bar-service.yaml"
- name: "Name used for this file"
path: "foobar.yaml"
useProxy: true
grpc:
servers:
- address: 127.0.0.1
port: 8080
protobufs:
"path/spec.proto": {}
"path/spec2.proto":
name: test
servers:
- address: 127.0.0.1
port: 8080
name: other server
useTls: true
```

```yaml
# Service's name.
# If this field does not provide the service name will be inferred from the repository URL
# Example: "https://github.com/MyOrg/MyRepo" -> "MyOrg/MyOrg"
# name = "service name"
# useProxy activate the proxy for the interface. Otherwise your service might needs to activate CORS
# List of OpenApi spec files or directories
# This list can be a mixed of string (path)
# or an object:
# name: Name of this service
# useProxy: activate the proxy for the interface. Otherwise your service might needs to activate CORS
specifications = []
```

If you intend to use the Github option you need to provide a token.
This token can be generated [here](https://github.com/settings/tokens/new).
You will need to allow:

- `public_repo` if you want to list public repositories
- `repo`: if want to list public and private repositories

### Docker

```sh
docker pull unisonui/unisonui

docker run -p 8080:8080 unisonui/unisonui

```

Options can either be passed as an environment variable or as a parameter.

To override the default value for a configuration entry (found in the
`reference.conf` files) just pass the `HOCON` path preceded by `-D`

```sh
docker run -p 8081:8081 unisonui/unisonui -Dunisonui.http.port=8081
```

There is a special case for configuration fields that are arrays.
You need to append the path by the index:
`unisonui.providers.0=unisonui.providers.docker.DockerProvider`

If you prefer you can use an environment variable instead.
For that take the path, uppercase it and replace the `.` by `_` and `-` by `__`.

```sh
docker run -p 8081:8081 -e RESTUI_HTTP_PORT=8081 unisonui/unisonui
```
More information available at [https://unisonui.tech](https://unisonui.tech)

0 comments on commit 9defc3a

Please sign in to comment.