ALPS ASD

Visualize Application Semantics and Affordance in REST Architecture

The diagram is hypermedia in SVG format with application states and state transitions linked to the respective semantic descriptor document HTML. The semantic descriptor document HTML is also linked to each other to represent the structure of the REST application.

Documentation

• https://alps-asd.github.io/

Output Demo

See online demo.

• blog
• todomvc

Run

There are three ways to run it: Run locally, Run with docker, and Git Hub Action.

Run with GitHub action

You can try ASD in a minute without installing any tools.

1. Click Use this template in alps-skeleton site to create ALPS skeleton. Please make the repository public for GitHub Pages.
2. Configuring a publishing source for your GitHub Pages site. Choose gh-pages and /(root) for the source.
3. Each time you commit, ASD diagram and hyper linked document will be generated in https://{user}.github.io/{repository}/.

Run with Docker

This is the most standard way.

curl -L https://alps-asd.github.io/app-state-diagram/asd.sh > ./asd && chmod +x ./asd && sudo mv ./asd /usr/local/bin

Run demo

Perform the following steps and open http://localhost:3000

mkdir work
curl -L curl https://alps-asd.github.io/app-state-diagram/blog/profile.json > work/profile.json
asd --watch ./work/profile.json

ASD documen appeared? Congratulations! Press the star in this repository to celebrate. 🌟

Usage

asd [options] [alpsFile]

    -c, --config=asd.xml
        Path to a asd.xml configuration file

    -w, --watch
        Watch mode

    -m, --mode={markdown|html}
        Output format
        
    --port
        Port number used in watch mode

• Supports XML and JSON formats.
• If you run it without the arguments,asd.xml config file in the same folder is used.

Run locally

This method is currently mainly for developers. It is tedious and time consuming.

Requirement

• php
• composer
• npm

You can check with the following command.

% php -v
PHP 8.0.6 (cli) (built: May  8 2021 01:58:51) ( NTS )

% composer -V
Composer version 2.0.13 2021-04-27 13:11:08

% npm -v
7.17.0

Installation

composer global require koriym/app-state-diagram

Update

composer global update koriym/app-state-diagram

Usage

composer global exec asd -- [options] [alpsFile]

The options are the same as for the Docker version.

Configuration

ASD uses an XML config file (by default, asd.xml). A barebones example looks like this:

<?xml version="1.0"?>
<asd xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:noNamespaceSchemaLocation="https://alps-asd.github.io/app-state-diagram/asd.xsd">
    <alpsFile>profile.xml</alpsFile>
</asd>

Optional attributes

watch

<asd>
  <watch>[bool]</watch>
</asd>

You can start ASD development server with watch mode. Each time the profile file changes, the page is reloaded.

If you want to start with a specific port number, you can specify the port number at startup as follows.

<asd>
  <port>3001</port>
</asd>

markdown format

If your repository is private and your account is not a GHE or GHE Cloud account, you cannot make GitHub Pqges private. In such a case, you can output the document as Markdown and make the document private.

Unfortunately there is no way to host linked SVGs (diagrams) in Markdown, the dialog will lose the link when in Markdown.

This is an option if public HTML is not possible.

<asd>
  <mode>markdown</mode>
</asd>