Skip to content
GitLab

Add new Plantuml generator for creating a schema diagram

Merged Administrator requested to merge github/fork/pburls/plantuml-generator into master

Created by: pburls

Resolves #6236 (closed)

In the issue above, I recently requested a way to generate a "Class Diagram" for the schemas in an OpenAPI spec.

This PR attempts to resolve this by adding a new "plantuml" documentation generator that generates a schemas.plantuml file that contains a Class plantuml diagram code (with some Entity diagram syntax).

The following diagram features are provided by this generator:

  • A diagram entity is created for each schema model
  • Each property is added as fields to the entity
    • Required properties are marked with a dot in front
    • The type of each property is added after the field name
  • A diagram "arrow" is created between schema models for properties referencing other schemas ("composition relationship").
    • The relationship is annotated with the name of the referencing property
    • If the referencing property is a List, the relationship is annotated with a "0..*" label.
  • A diagram "arrow" is created between schema models for composed schemas using allOf syntax ("inheritance relationship").
    • The inheritance arrow head is directed to the "super type" being inherited

The petstore.yaml sample spec results in the following rendered plantuml diagram: OpenAPI Petstore Schemas Diagram

The allOf.yaml sample spec results in the following rendered plantuml diagram: Example Schemas Diagram

PR checklist

  • Read the contribution guidelines.
  • If contributing template-only or documentation-only changes which will change sample output, build the project before.
  • Run the shell script(s) under ./bin/ (or Windows batch scripts under.\bin\windows) to update Petstore samples related to your fix. This is important, as CI jobs will verify all generator outputs of your HEAD commit, and these must match the expectations made by your contribution. You only need to run ./bin/{LANG}-petstore.sh, ./bin/openapi3/{LANG}-petstore.sh if updating the code or mustache templates for a language ({LANG}) (e.g. php, ruby, python, etc).
  • File the PR against the correct branch: master, 4.3.x, 5.0.x. Default: master.
  • Copy the technical committee to review the pull request if your PR is targeting a particular programming language. (None exist for plantuml)