openapi-to-plantuml

Java library to generate a PlantUML Class Diagram (supplemented with path information) from an OpenAPI 3.0 definition (YAML or JSON). Try it online here.

Features

Supports all features of OpenAPI 3.0 including

• Mixed types (oneOf, anyOf, allOf)
• Multiple levels of indirection ($ref -> $ref for example)
• Multiple response content types
• Can produce diagram-per-path (great for large APIs)

Status: Released to Maven Central

Limitations

• Only handles internal references ("#/*"), that is the yaml file should be self-contained. As of 0.1.9 external refs are displayed but not exploded. Full external reference support is being considered.

TODO

• Model Callbacks
• Model additionalProperties

openapi-example.yml:

How to build

mvn clean install

How to quickly convert your OpenAPI definition

The easiest thing to do is to use the online converter. If your definition is large then PlantText may refuse to render it (the Plant UML text is encoded and added to the PlantText url which can get too long). In that case just add your yaml file to src/test/resources/demo/ directory and run mvn test. The generated image will be saved in target/demos.

Getting started

Add this dependency to your pom.xml:

<dependency>
  <groupId>com.github.davidmoten</groupId>
  <artifactId>openapi-to-plantuml</artifactId>
  <version>VERSION_HERE</version>
</dependency>

Or use the standalone jar-with-dependencies artifact from Maven Central (or from the target directory if you have built the project locally):

How to produce a single diagram

java -jar openapi-to-plantuml-VERSION_HERE-jar-with-dependencies.jar single openapi.yaml PNG openapi.png

Large diagrams are better with SVG format (rendering is sharp at every zoom level) so just replace PNG in the above command with SVG. If you still want a PNG and you find it is getting cut off then you need to increase the plantuml image size limit like below. Increase the limit till your diagram fits. You may need to increase memory using this JVM arg -Xmx1024m.

java -DPLANTUML_LIMIT_SIZE=8192 -jar openapi-to-plantuml-VERSION_HERE-jar-with-dependencies.jar openapi.yaml PNG openapi.png

How to produce a diagram per service method

java -jar openapi-to-plantuml-VERSION_HERE-jar-with-dependencies.jar split openapi.yaml PNG diagrams

The above call will write a diagram per method into the diagrams directory (and will create it if it doesn't exist).

As an example, do mvn clean test on the project and look in target/unqork.svg directory.

Usage

import com.github.davidmoten.oas3.puml.Converter;

String puml = Converter.openApiToPuml(openapi);

System properties

• max.enum.entries defaults to 12. If an enum has more than the max then it will be limited to that number and an entry ... will appear at the end of the enums.

Examples

Unit test examples are here.

petstore-expanded.yml:

bookstore.yml:

ecommerce.yml

news.yml:

strava.yml:

twitter.yml:

ebay.yml: