openapi2puml / openapi2puml Goto Github PK

If the swagger specification contains multiple types of error response, the generated PlantUML diagram contains invalid syntax.

For example - below the HTTP 400 response uses an "ErrorMessage" structure and the HTTP 404 response uses a "WarningMessage" structure:

  '/cat/{catId}':
    get:
      tags:
        - cat
      summary: Find cat by ID
      description: Returns a single cat
      operationId: getCatById
      produces:
        - application/xml
        - application/json
      parameters:
        - name: catId
          in: path
          description: ID of cat to return
          required: true
          type: integer
          format: int64
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/Cat'
        '400':
          description: Invalid ID supplied
          schema:
            $ref: '#/definitions/ErrorMessage'
        '404':
          description: Cat not found
          schema:
            $ref: '#/definitions/WarningMessage'

The resulting PlantUML contains this definition for the relationship which is not valid.

CatApi --> ErrorMessage,WarningMessage

when i call the program -o ../dadad/dudu
the puml file goes there, but svg goes into
../dadad/dudu/dadad/dudu

Allow running the application without having to install all the dependencies etc.

The fat jar generated with dependencies contains unneccessary jar files (e.g. mockito) that could be left out to reduce the size of the final jar.

Correct use of a scope for each dependency in the Maven pom files should be a solution.

The current code uses the inbuilt java.util logger classes and is quite verbose without really adding anything useful - i.e. entry and exit of methods is logged even if successful, no real information is logged if an error occurs.

The enhancement would be to:

• Move to either slf4j or log4j2 (or another logging system) to allow a finer granularity of logging
• Refactor the logging calls to remove some calls and add some useful summary information - e.g. list all the operations parsed from Swagger etc.

Rename and refactor all poms, packages and documents to use the new project name

Setup the following:

• Travis CI for continous integration
• Codecov.io for test coverage - this requires the project to have some code coverage such as cobertura
• Maven for using the core jar as a dependency - this could be optional for now

The image generation for SVG is done by invoking the main method of the Run class from the PlantUML library.

This seems to not work well with JUnit tests and is a strange approach to the image file generation.

This enhancement should follow the example from the PlantUml site - http://plantuml.com/api
It uses the class SourceFileReader to read the generated PlantUML file and to generate the resulting image file.

This is a copy of an issue opened on the original swagger2puml repository which was never fixed.
kicksolutions/swagger2puml#41

The issue was opened and a patch solution proposed by @stroisi (https://github.com/stroisi)

I also took the patch solution, added some simple unit tests and opened a PR on the original repository which has never been merged.

Original Issue description below:

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
  }`

Original Zip file with patch:
multiple-inheritence-npe-patch.zip

The current maven build and usage descriptions are somewhat misleading.
The jar built by default does not include dependencies and so the usage instructions as given in the readme do not work.

A solution is already provided on the original Swagger2Puml repository (kicksolutions/swagger2puml#40)
submitted by @dgileadi

@dgileadi - please feel free to submit a PR here with your fix

When a path has multiple operations, instead of this mapping to a single Interface with multiple methods, an Interface item is created with one single method for each operation.
These Interface items are added to the list of interface items and this is used by the mustache template to build the final uml output.

PlantUML viewers seem to be smart enough to merge these multiple definitions into one but it would be better to organize the data model objects better.

My YAML file is correct but this plugin does not accept it:
Error:

Invalid OpenAPI definition
[pointer: "",
message: object instance has properties which are not allowed by the schema: ["components","openapi","servers"]
, pointer: "",
message: object has missing required properties (["swagger"])
]

There is a mix of styles in the project with different spacing etc.
There are also empty comments.

This issue will be to apply consistent style conventions to the code and commenting.

The PlantUMLCodegen class can be refactored to make it more testable.

The aim would be to test its individual functionalities separately.

When running unit tests or from the jar, there are multiple svg file copies created.
I suspect this comes from just getting all created files so the solution may be to get just a specific file instead.

The definition section is fine, but the "graphic" section with the arrows is broken as the names are not quoted

e.g.:
Discovery-document-controllerApi --> IdpJwksDocument
should be
"Discovery-document-controllerApi" --> IdpJwksDocument

Hi, notice that it cannot convert api specs from v2 onwards. Will you support for open api v3 definition?