ALPS ASD
Produces a full application state diagram and hyperlinked documentation from ALPS file.
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
Output Demo
See online demo.
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.
- Click Use this template in alps-skeleton site to create ALPS skeleton. Please make the repository public for GitHub Pages.
- Configuring a publishing source for your GitHub Pages site. Choose
gh-pages
and/(root)
for the source. - 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.
Pull the docker image and install ASD utility.
docker pull ghcr.io/alps-asd/app-state-diagram:latest
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
--and-tag={tag1, tag2} --or-tag={tag3} [--color=red]
Filter graph
-l, --label={id|title|both}
Displayed words
-m, --mode={markdown|html}
Output format
- 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
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
% dot -V
dot - graphviz version 2.47.1 (20210417.1919)
% 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.
filter
<asd>
<filter>
<and>[string]</and>
<and>[string]</and>
<or>[string]</or>
<color>[string]</color>
</filter>
</asd>
You can extract partial graphs by specific tags, or color specific graphs.
Specify a tag name in the "or" or "and" field to specify the condition. If you specify "color", the graph for that condition will be colored, but if you don't, only the graph for that condition will be extracted and drawn.
label
<asd>
<label>[string]</label>
</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>