Authoring with RESTalk DSL

[tpluscode]

I see that the patterns have been created in Inkscape. Do you have some extension to Inkscape or is it alone enough to create the conversation diagrams?

[ivanchikj]

We do not use any extensions currently. Here is a template of the RESTalk constructs we currently use: RESTalk_template.svg.zip

[tpluscode]

It's still SVG. What would you think about an online tool to create RESTalk diagrams? I've started experimenting with SVG <symbol> tag to extract reusable parts and put them inside a Polymer Web Component.

https://codepen.io/tpluscode/pen/ALWmzE?editors=1010

A hack is required for the repeater to work and dragging is not perfect but it works :). For starter I expect connectors to be automatically adjusting when you drag the requests/responses. Would you be interested is something like this?

[saivlis]

This looks quite interesting, especially as there is a need for tool support for such diagrams. So feel free to elaborate in more detail and please keep us up-to-date.

[asbjornu]

The optimal solution, to me, would be to extend PlantUML so RESTalk could have its own textual syntax with a standardised conversion into SVG and PNG. Just as an example, this:

@startuml
:Main Admin: as Admin
(Use the application) as (Use)

User -> (Start)
User --> (Use)

Admin ---> (Use)

note right of Admin : This is an example.

note right of (Use)
  A note can also
  be on several lines
end note

note "This note is connected\nto several objects." as N2
(Start) .. N2
N2 .. (Use)
@enduml

When fed through the PlantUML converter, turns into this:

Having diagrams written in terse, expressive plain text makes it fit well alongside the source code of the API it is documenting, making versioning, diffing, merging, etc., as simple as it is with regular source code.

[tpluscode]

Is it possible to extend PlantUML with custom building blocks?

I got a number of suggestions for diagramming listed on tpluscode/restalk-editor#2 (including PlantUML too). Some of those do actually work similarly where you author a text description and the diagram is a side effect.

[asbjornu]

Is it possible to extend PlantUML with custom building blocks?

The PlantUML source code is hosted on SourceForge, (and they push it to GitHub too) so I assume that at worst, you can fork it and add whatever you want.

But I assume that the source code is sensible enough that each diagram type is implemented such that adding new ones should be pretty straight forward. It's Java, though.