All files live in the gh-pages branch
tas-des-static is a set of static resources (shell scripts, node scripts, javascript and CSS) that we use at Talent App Store for some of our design documentation.
tas-des-static helps with:
- structured design documents - the builddes.sh script can parse a bunch of raml API definition files, and json example and schema files, and:
- check the raml is valid
- check the json examples conform to their schemas
- generate an index.html file and a documentation from RAML and JSON files
- unstructured design documents (plain .html files) - tas-des-static provides javascript and css files that enable useful behaviours and styles for human-written design documents, e.g.:
- auto-generate a table of contents from the document's header tags
- render sequence diagrams
- include other files within a master design document using ajax
See the comments within builddes.sh for details of the directories etc. for your structured design files (raml and json).
Then git clone the tas-des-static repo onto your local file system and then build your design documentation like this:
[localhost tas-core-apis]$ cd ~/git/tas-core-apis
[localhost tas-core-apis]$ ../tas-des-static/scripts/builddes.sh .
Review the output for errors:
validating all schemas
looping to load all schemas
adding schema: patchSet.json
adding schema: patchSetLaunchKey.json
adding schema: patchSetPreparer.json
adding schema: patchSetStatus.json
done adding schemas
looping to test schemas by validating their corresponding examples
schema: patchSet.json
example: patchSet-installApp.json
example: patchSet-installAppWithServer.json
example: patchSet-newStore.json
schema: patchSetLaunchKey.json
example: patchSetLaunchKey-simple.json
done validating
generating HTML
generating coreIn.raml.html from coreIn.raml
generating coreOut.raml.html from coreOut.raml
done generating HTML
tas-des-static provides a bunch of useful features for authoring design documents, which are held as plain html files and can be hosted on any server (including github static hosting).
Most tas-des-static behaviour happens client-side via Javascript, so you can mostly preview your design document as a file on your file system. However the "clientInclude" feature relies on ajax and thus only works when your files are hosted on a web server - one easy way to do this is to install tomcat and point it at your file system as per http://www.moreofless.co.uk/static-content-web-pages-images-tomcat-outside-war/.
<Host appBase="webapps"
...
<Context docBase="/home/stuff" path="/static" />
</Host>
You can use something like ngrok to share your localhost web site with the world.
Create a plain html document to hold your design.
Within the head of your design document, include the relevant files to support the features you will use in your document.
<!-- always required -->
<script src="http://ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js"></script>
<!-- needed for sequence diagrams -->
<script type="text/javascript" src='http://talentappstore.github.io/tas-des-static/js/raphael-min.js'></script>
<script type="text/javascript" src='http://talentappstore.github.io/tas-des-static/js/underscore-min.js'></script>
<script type="text/javascript" src='http://talentappstore.github.io/tas-des-static/js/sequence-diagram-min.js'></script>
<script type="text/javascript" src='http://talentappstore.github.io/tas-des-static/js/sequence-diagram-wrapper.js'></script>
<!-- needed for includes -->
<script type="text/javascript" src='http://talentappstore.github.io/tas-des-static/js/clientInclude.js'></script>
<!-- needed for table of contents -->
<script type="text/javascript" src='http://talentappstore.github.io/tas-des-static/js/tocify.js'></script>
<!-- always required -->
<link rel='stylesheet' href='http://talentappstore.github.io/tas-des-static/css/des.css' type='text/css' media='all' />
You can include sequence diagrams as per the example below.
Each diagram needs the class 'seqDiag', and a unique id. See https://github.com/bramp/js-sequence-diagrams for more details.
It is optional to list the participants up front, but doing so makes it easier to swap around the order to your liking once the diagram is otherwise complete.
<div class='seqDiag' id="uniqueId">
participant TAS
participant jobsite app
participant preferences app
note right of jobsite app: user is already SSO-ed in at jobsite\nsession holds PrincipalAuthnId = 52034
jobsite app->TAS: GET /acme/authentications/viaSso/52304
note right of TAS: Response:\n{ "personDetail":{ "email":"fred@hotmail.com"
note right of jobsite app: Now jobsite knows who the user is.\nThat is not required to make the OAuth\ncall, but shown for completeness.\nFetch the route for the API we want to call
jobsite app->TAS: GET /acme/routes/jobsite/tas/%2FuserPreferences%2F%7Bemail%7D
note right of TAS: Response:\n"producer": "preferences",\n"location": "https://acme.preferences.com/",\n"auth": { "kind": "oauthAuth" }
note right of jobsite app: API is OAuth, so we need an access token
jobsite app->TAS: GET /acme/routes/jobsite/tas/%2FuserPreferences%2F%7Bemail%7D\n/preferences/tokens/viaSso/52304
note right of TAS: Response:\nan access token
note right of jobsite app: Now jobsite can make the OAuth API call
jobsite app->preferences app: GET https://acme.preferences.com/api/userPreferences/fred@hotmail.com\n(passing access token in Authorization header)
note left of preferences app: preferences app needs tenant publicKey to validate the access token
preferences app->TAS: GET /acme
note left of preferences app: token is OK, preferences app now performs\nadditional tests, e.g. aud == 'preferences',\ninc == tenant.incarnation
note left of preferences app: allows the API call
</div>
To include a dynamically generated table of contents, insert a div as below at the top of your document.
The table of contents will be generated from the header tags (h1, h2, etc.) in your document and inserted within the div.
<div id="toc"></div>
You can pull in content, such as example code held in separate files, using clientInclude:
<div class='clientInclude' data-href='./frig.html'></div>
To test clientIncludes, your design document needs to be hosted on a web server.
You can use clientInlcude to pull in the content of a codeBlock like this:
<div class='codeBlock'>
<div class='clientInclude' data-href='../examples/patchSet-installApp.json'></div>
</div>
Mark up code blocks like this:
<div class='codeBlock'>
POST /m/jobs/{}/deltaPings
</div>
Finally, make it all happen at render time by adding an onReady() handler at the end of your document:
<script>
$(document).ready(function() {
// comment out features you don't use
renderSequenceDiagrams();
renderClientIncludes();
renderTOC();
});
</script>