Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add new Plantuml generator for creating a schema diagram #6255

Merged
merged 25 commits into from
May 14, 2020

Conversation

pburls
Copy link
Contributor

@pburls pburls commented May 11, 2020

Resolves #6236

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)

@pburls pburls marked this pull request as ready for review May 13, 2020 08:28
Patrick.Burls added 2 commits May 13, 2020 15:21
@wing328
Copy link
Member

wing328 commented May 14, 2020

@pburls thanks for the PR, which looks good to start with. I may file another PR with very minor improvements.

@wing328 wing328 merged commit f03458d into OpenAPITools:master May 14, 2020
@wing328 wing328 added this to the 5.0.0 milestone May 14, 2020
@wing328
Copy link
Member

wing328 commented May 14, 2020

@pburls I've filed #6298 with the improvements.

@pburls pburls deleted the plantuml-generator branch May 14, 2020 20:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging this pull request may close these issues.

[REQ] Generate a Class Diagram for complex Schemas
2 participants