GraphQL Extension for StarUML 3

This extension for StarUML(http://staruml.io) supports the generation of GraphQL IDL schemas from UML models.

What's new

June 29th 2018:

New Feature: StarUML3 support, enjoy!

Past:

Bug: Fixed a extend statement bug with the following structure Class->AbstractClass->Class
New Feature: Give great flexibility to your diagram but using Abstract classes. Abstract classes keept their full meaning in a class hierachy, but are not generated.
New Feature: Allow graphQL generation in a ui panel
New Feature: You may now generate from the top project level
New Feature: Added graphql file generation from context menu (right click on element)
New Feature: Generated filename is now based from the picked element
New Feature: Added a preference to control debug output
New Feature: Unnamed associations are given a more meaningful name based on the entities they link. They are also pluralized when applicable
New Feature: Attribute/Realtionship naming overrides are now properly implemented between attribute types , associations and hierarchies
Bug: Default parameter value wasn't generated for mutators
Bug: Removed (c)copyright from preferences as this information is redundant with Project.copyright
Bug: Cardinality generation was off
Extra: Added a few more examples

Installation

Install this extension from StarUML's Extension Manager.

Usage

Click the menu (Tools > GraphQL > Generate Code...)
Select a base model (or package) that will be generated to GraphQL.
Select a folder where generated GraphQL source files will be placed.

file schema.gql will be generated at destination

Generation

Disclaimer: Neither StarUML nor this generator can enforce the limitations governed by the GraphQL expression language. It is of your responsibility to create data structures that will comply with the GraphQL specifications.

###GraphQL IDL Notation

Let's start with the basics.

###Classes, Default values & Directives

So let's start with a basic class generation. Here class attributes are given a type and a default value. We also made v3 a required field. Finally we added documentation here and there to demo what the generator does.

# name: GraphQL Generation Samples
# version: 1.0
# author Olivier Refalo
# copyright (c) Olivier Refalo

# Just a few comments to demo documentation generation.
type MyClass {

    v1: String="helloworld"
    v2: Int=5
    # This field is required, it has a multiplicity=1
    v3: String!
}

GraphQL offers a great way to implement custom behaviors using @directives. Using StarUML than can be modelled as Tags (if they need to be visually visible) or constraints. In the sample below, @const1 is not "visible"

type DirectiveClass {
    name: String @fake(type: firstName) @const1(value1)
    gender: String @examples(values: ["male", "female"])
}

###Scalars & Enums

Scalars and Enumerations are supported by StarUML's native Primitive and Enumeration types. Please ensure you use these native StarUML types in order to generate the expected artifacts.

scalar UUID
scalar Date

enum Enumeration1 {
    L1
    L2
    L3
}

###Union types

Union types are defined by using Dependencies. Typically Unions do not carry any attributes or relations. The generator will warn when it encounters such structure.

type Cat {

}

# test class doc
type Dog {

    f1: String!
    # test field doc
    f2: String
    toInvalidUnion: InvalidUnion
}

union AnimalUnionType = Cat | Dog

# WARNING: Attributes on union types is not GraphQL compliant, ignoring.

###Associations, Aggregation & Composition

Important facts, associations are:

directional
multiplicity aware
automatically named, unless specified (either on each end, or on association itself)

type Class3 {

    toC4: [Class4]!
}

type Class4 {

    name: String
    gender: String
    toC3: Class3!
}

type Class1 {

    query: [Class2]!
    mutation: Class5
}

type Class2 {

    query: Class1
}

type Class5 {

}

type Team {

    subteams: [Team]
    parent: Team
    builds: [Airplan]!
    teams: [Employee]!
}

type Airplan {

    toComponent: [Component]!
}

type Employee {

    members: [Team]
}

type Component {

    toAirplan: Airplan!
    subassembly: [Component]
    assembly: [Component]
}

###Class and Interface hierarchies

Unlike GraphQL syntax, there is no need to repeat the attribute definition across the hierarchy. The generator takes care of it, Neat!

type Vehicule {

    id: ID
}

type Car extends PassengerVehicule {

    noOfDoors: Int
    nrOfPasssengers: Int!
    id: ID
}

type Truck extends TransportationVehicule {

    numberOfCountainers: Int
    loadCapacity: Int
    id: ID
}

type TransportationVehicule extends Vehicule {

    loadCapacity: Int
    id: ID
}

type PassengerVehicule extends Vehicule {

    nrOfPasssengers: Int!
    id: ID
}

type Bike extends PassengerVehicule {

    saddleHeight: Float
    nrOfPasssengers: Int!
    id: ID
}

Here we use InterfaceRealization to implement an interface in a new class. Note how the child attributes are automatically inherited from the parent interface.

type Bar implements Foo {

    is_bar: String
    is_foo: String
}

type Baz implements Foo, Goo {

    is_baz: String
    is_foo: String
    is_goo: String
}

interface Foo {

    is_foo: String
}

interface Goo {

    is_goo: String
}

Finally a example showing interface extension.

type Class1 {

    r1: Class2
}

type Class2 {

}

type ClassB {

}

type ClassA {

    r2: ClassB
}

interface I1 {

    f1: Int
    i1ToC22: ClassA
    i1ToC1: Class1
}

interface I2 extends I1 {

    f1: Int
    i1ToC22: ClassA
    i1ToC1: Class1
}

###Schemas, Mutations

type RootMutation {

    createTodo(input: CreateTodoInput!) :  CreateTodoPayload

    toggleTodoCompleted(input: ToggleTodoCompletedInput!) :  ToggleTodoCompletedPayload

}

schema {
    mutation: RootMutation!
}

# `id` is generated by the backend, and `completed` is automatically set to false
input CreateTodoInput {

    text: String!
}

type Todo {

    id: ID
    text: String
    completed: Boolean
}

type CreateTodoPayload {

    todo: Todo!
}

input ToggleTodoCompletedInput {

    id: ID!
}

type ToggleTodoCompletedPayload {

    todo: Todo
}

Rules

The following rules apply during generation.

Project Metadata

name, company, version, author and copyright are used to generate the document header.

UMLPackage

ignored - but browsed recursively for other uml entities.

UMLPrimaryType

converted to GraphQL scalar.

UMLClass

converted to GraphQL type.
Abstract class are not generated, but still part of the hierarchy.
union stereotype converted to an union type, using dependency connections to related types.
input stereotype converted to an input type.
schema stereotype converted to a GraphQL schema.
Full support for UML inheritance and interface - no need to repeat attributes across the hierarchy.
Documentation property to GraphQL comment.

UMLAttribute

converted to GraphQL Field.
name property to field identifier.
type property to field type, defaults to String.
multiplicity property to array type and/or required constraint.
GraphQL directives implemented via attribute's Tag(name, value)
GraphQL directives can also be modeled via an attribute Constraint(name, specification) - in which case they will not display in the diagram
Default values generation.
Documentation property to GraphQL comment.

UMLOperation

converted to GraphQL mutator.
name property to method identifier.
UMLParameter to GraphQL Method Parameters.
UMLParameter's name property to parameter identifier.
UMLParameter's type property to type of parameter.
UMLParameter's multiplicity property to array type and/or required constraint.
UMLParameter with direction = return to return type of method.
GraphQL directives implemented via attribute's Tag(name, value)
GraphQL directives can also be modeled via an attribute Constraint(name, specification) - in which case they will not display in the diagram
Documentation property to GraphQL comment.

UMLInterface

converted to GraphQL Interface. (as a separate .ts file)
Documentation property to GraphQL comment.

UMLEnumeration

converted to GraphQL enum.
UMLEnumerationLiteral to literals of enum.

UMLAssociationEnd

support for associations, aggregations and compositions
be careful, by default starUML create bi-directional associations(like) relations. Use the "navigable" flag to pick on which side the accessor should be generated.
converted to GraphQL Field.
name property to field identifier.
type property to field type.
Documentation property to GraphQL comment.
multiplicity property to array type and required constraint.

Cardinality property	=> Generation
0..1	field
1	field!
n n>1	[field!]
0..* or *	[field]
1..*	[field!]

UMLGeneralization

converted to GraphQL extends or GraphQL implements.
Allowed only for UMLClass to UMLClass, and UMLInterface to UMLInterface.

UMLInterfaceRealization

converted to GraphQL Implements.
Allowed only for UMLClass to UMLInterface.

FAQ

How to create comments?

Ensure Preference's option is turned on, use starUML documentation area. The generator will pick it up.

How to create a union?

A Union is a class with a union stereotype, types are referenced via a Dependency relationship

How do I get a schema.json from the IDL file?

Use gqlschema from npm's gql-tools

I can't see Interface's attributes in diagrams

That StartUML default interface rendering. Right click on the interface, from the context menu, pick Format > Stereotype display > Decorations and labels

How to make an attribute required?

Select the attribute, the parameter or the relationship
Depending on what you want to make 'required', use one of the multiplicity below

Cardinality property	=> Generation
1	field!
n n>1	[field!]
1..*	[field!]

Contributing

Clone this repo somewhere on your dsk
Create a branch and switch to it
Go to StarUML.app/Contents/www/extensions/dev
ln -s <git_repo> staruml-graphql
Relaunch StarUML - a Debug menu will now show
Do your changes, commit and submit a pull request

To Do

Add/remove graphql-faker directives with a context-menu entry

About the Author

My name is Olivier Refalo, author behind this StarUML extension. I am an Innovator, a Digital transformer, a skilled Architect, a Leader and an Entrepreneur.

Over the years I grew extensive knowledge around data modeling, reactive technologies, business processes, integrations and enterprise architecture. Lately I grew my technical skills around GraphQL which I see as an elegant way to solve the "middleware mess" with an inversion of control approach.

I believe in open source as a way to drive innovations and share knowledge, this project is yet another way to contribute back to the community. With that said, if you do use this project, please consider:

Buying StarUML
Making a donation

Thank you

Licensed under GPLv3

israelagoeiro/staruml3-graphql