This extension for StarUML(http://staruml.io) supports the generation of GraphQL IDL schemas from UML models.
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
Install this extension from StarUML's Extension Manager.
- 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
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
}
The following rules apply during generation.
- name, company, version, author and copyright are used to generate the document header.
- ignored - but browsed recursively for other uml entities.
- converted to GraphQL scalar.
- converted to GraphQL type.
- Abstract class are not generated, but still part of the hierarchy.
unionstereotype converted to an union type, using dependency connections to related types.inputstereotype converted to an input type.schemastereotype 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.
- converted to GraphQL Field.
nameproperty to field identifier.typeproperty to field type, defaults to String.multiplicityproperty 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.
- converted to GraphQL mutator.
nameproperty 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
multiplicityproperty to array type and/or required constraint. - UMLParameter with
direction=returnto 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.
- converted to GraphQL Interface. (as a separate
.tsfile) - Documentation property to GraphQL comment.
- converted to GraphQL enum.
- UMLEnumerationLiteral to literals of enum.
- 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.
nameproperty to field identifier.typeproperty to field type.- Documentation property to GraphQL comment.
multiplicityproperty to array type and required constraint.
| Cardinality property | => Generation |
|---|---|
| 0..1 | field |
| 1 | field! |
| n n>1 | [field!] |
| 0..* or * | [field] |
| 1..* | [field!] |
- converted to GraphQL extends or GraphQL implements.
- Allowed only for UMLClass to UMLClass, and UMLInterface to UMLInterface.
- converted to GraphQL Implements.
- Allowed only for UMLClass to UMLInterface.
Ensure Preference's option is turned on, use starUML documentation area. The generator will pick it up.
A Union is a class with a union stereotype, types are referenced via a Dependency relationship
Use gqlschema from npm's gql-tools
That StartUML default interface rendering. Right click on the interface, from the context menu, pick Format > Stereotype display > Decorations and labels
- 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!] |
- 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
- Add/remove graphql-faker directives with a context-menu entry
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