kicksolutions/swagger2puml

Generate Class Diagrams (UML) for Given Swagger Definition

Swagger2Puml

Swagger to Puml convertion tool helps to generate Class Diagrams from Swagger Definition.

This Project is based on Maven and plan to support Gradle also in future. Following are modules we currently have

• swagger2puml-core
• swagger2puml-maven

Following are the tools which this project internally uses:

• Swagger Parser
• Plant UML
• Graphviz
• Mustache

Please install Graphviz on your machines, ensure you edit PATH varible of your machine and add bin folder of graphviz.

Create a new System Variable called GRAPHVIZ_DOT and point to dot.exe for windows and dot in case of Linux in bin folder of graphviz.

How does it work

• Swagger2Puml internally reads the swagger definition using Swagger Parser which then converts the Swagger Definition to swagger.puml
• Once the swagger.puml gets generated sucessfully it then calls Plant UML to generate swagger.svg

swagger2puml-core:

This utility takes Swagger Yaml as input and as response it generates swagger.puml and swagger.svg files as output.

Below is the Sample Class Diagram which gets generated. To see the generated PUML file, please click here

Usage:

java -cp swagger2puml.jar com.kicksolutions.swagger.Swagger2PlantUML [options]

-i {Path of Swagger Definition (Can be either Yaml or json)}
-o {Target location where Puml File and Image should generated}
-generateDefinitionModelOnly {true/flase Defult False (Optional)}
-includeCardinality {true/flase Defult true (Optional)}
-includeCardinality {true/flase Defult true (Optional)}

swagger2puml-maven

This Maven plugin is Mojo, which internally calls swagger2puml-core to generate swagger.puml and swagger.svg for given Swagger Definition. Swagger Definition can be either yaml or json extensions.

License

Apacahe 2.0

swagger2puml's Issues

Usage detail

Hello,

I tried using your tool, but found the documentation to be a bit unclear on how to do so. Here's what I did:

• cloned the repo
• did a mvn clean install

But I can't find the swagger2puml.jar that is mentioned in the docs.

What am I missing ?

Thanks a lot for your help :)

All the best;

NPE when using multilevel inheritance

When processing a yaml with definitions that include multiple levels of inheritance an NPE is thrown.

Example model:
`

  GrandParentObj:
    discriminator: objType
    required:
      - objType
    properties:
      prop1:
        type: string
      objType:
        type: string

  ParentObj:
    allOf:
      - $ref: '#/definitions/GrandParentObj'
      - type: object
        properties:
          prop2:
            type: string
        
  ChildObj1:
    allOf:
      - $ref: '#/definitions/ParentObj'
      - type: object
        properties:
          prop3:
            type: string`

NPE Stacktrace:
`

Caused by: java.lang.NullPointerException
    at java.util.HashMap.putMapEntries (HashMap.java:501)
    at java.util.HashMap.putAll (HashMap.java:785)
    at com.kicksolutions.swagger.plantuml.PlantUMLCodegen.getClassMembers (PlantUMLCodegen.java:745)
    at com.kicksolutions.swagger.plantuml.PlantUMLCodegen.getClassMembers (PlantUMLCodegen.java:693)
    at com.kicksolutions.swagger.plantuml.PlantUMLCodegen.processSwaggerModels (PlantUMLCodegen.java:577)
    at com.kicksolutions.swagger.plantuml.PlantUMLCodegen.preprocessSwagger (PlantUMLCodegen.java:120)
    at com.kicksolutions.swagger.plantuml.PlantUMLCodegen.generatePuml (PlantUMLCodegen.java:83)
    at com.kicksolutions.swagger.plantuml.PlantUMLGenerator.transformSwagger2Puml (PlantUMLGenerator.java:43)
    at com.kicksolutions.swagger.Swagger2PlantUML.process (Swagger2PlantUML.java:71)
    at com.kicksolutions.swagger.Swagger2PlantUML.init (Swagger2PlantUML.java:55)
    at com.kicksolutions.swagger.Swagger2PlantUML.main (Swagger2PlantUML.java:37)`

It looks like when the getClassMembers(ComposedModel) method loops over the "AllOf" list of the target model to resolve the parent model's properties, that if the parent is itself the child of another type that it's getProperties() method returns null, causing the NPE when we try to put them into the child's Map of properties.

I'm attaching a patch with a proposed fix.

There is a secondary issue, also addressed in the patch, which is that even with the NPE fixed the code wasn't correctly resolving the full list of properties from the descendant types.

In the example above, the UML generated for "ChildObj1" looked like:
`

class ChildObj1 {
- prop3 :String
}`

With the patch applied we recurse to get properties from the descendants, and the output includes prop1 & prop2 from the parent & grandparent types:
`

class ChildObj1 {
- prop3 :String
- prop2:String
- prop1:String
}`

Create swagger2puml core module

Create swagger2puml core module

It's called OpenAPI 😅

Howdy! I found this thing Goolging and it looks awesome. I want to put it on openapi.tools but wanted to point out: the specification has not been called Swagger for a long time.

The name of the specification is OpenAPI, and tools should probably use that in their name instead of Swagger, as that's just the name of the official set of tools (Swagger Codegen, Swagger UI, Swagger Editor).

Maybe rename to openapi2puml, and make the description "Generate Class Diagrams (UML) for Given OpenAPI (f.k.a Swagger) Definition" so it still shows up on Google for both searches.

Dockerfile

A Dockerfile would allow running the application without the need to install Java locally on e.g. a Mac computer for one diagram.

inheritance support?

Does uml gen support inheritance definition? I have got NPE when I tried to use json with inheritance definition.

INFO: Processing Model UICLParametrizationBonus
Mar 07, 2018 10:57:49 PM com.kicksolutions.swagger.plantuml.PlantUMLGenerator transformSwagger2Puml
SEVERE: null
java.lang.NullPointerException
	at com.kicksolutions.swagger.plantuml.PlantUMLCodegen.getClassMembers(PlantUMLCodegen.java:745)
	at com.kicksolutions.swagger.plantuml.PlantUMLCodegen.getClassMembers(PlantUMLCodegen.java:693)
	at com.kicksolutions.swagger.plantuml.PlantUMLCodegen.processSwaggerModels(PlantUMLCodegen.java:577)
	at com.kicksolutions.swagger.plantuml.PlantUMLCodegen.preprocessSwagger(PlantUMLCodegen.java:120)
	at com.kicksolutions.swagger.plantuml.PlantUMLCodegen.generatePuml(PlantUMLCodegen.java:83)
	at com.kicksolutions.swagger.plantuml.PlantUMLGenerator.transformSwagger2Puml(PlantUMLGenerator.java:43)
	at com.kicksolutions.swagger.Swagger2PlantUML.process(Swagger2PlantUML.java:73)
	at com.kicksolutions.swagger.Swagger2PlantUML.init(Swagger2PlantUML.java:57)
	at com.kicksolutions.swagger.Swagger2PlantUML.main(Swagger2PlantUML.java:39)

Exception in thread "main" java.lang.RuntimeException: java.lang.NullPointerException
	at com.kicksolutions.swagger.plantuml.PlantUMLGenerator.transformSwagger2Puml(PlantUMLGenerator.java:53)
	at com.kicksolutions.swagger.Swagger2PlantUML.process(Swagger2PlantUML.java:73)
	at com.kicksolutions.swagger.Swagger2PlantUML.init(Swagger2PlantUML.java:57)
	at com.kicksolutions.swagger.Swagger2PlantUML.main(Swagger2PlantUML.java:39)
Caused by: java.lang.NullPointerException
	at com.kicksolutions.swagger.plantuml.PlantUMLCodegen.getClassMembers(PlantUMLCodegen.java:745)
	at com.kicksolutions.swagger.plantuml.PlantUMLCodegen.getClassMembers(PlantUMLCodegen.java:693)
	at com.kicksolutions.swagger.plantuml.PlantUMLCodegen.processSwaggerModels(PlantUMLCodegen.java:577)
	at com.kicksolutions.swagger.plantuml.PlantUMLCodegen.preprocessSwagger(PlantUMLCodegen.java:120)
	at com.kicksolutions.swagger.plantuml.PlantUMLCodegen.generatePuml(PlantUMLCodegen.java:83)
	at com.kicksolutions.swagger.plantuml.PlantUMLGenerator.transformSwagger2Puml(PlantUMLGenerator.java:43)
	... 3 more
1 Michal-MacBook-Pro:target kolisko$ 

here is the definition file:

swagger.txt