Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/davidmoten/openapi-to-plantuml
Converts OpenAPI 3.0 definitions to Plant UML text for visualisation of your API.
https://github.com/davidmoten/openapi-to-plantuml
java online openapi openapi-documentation openapi3 plantuml uml-diagram
Last synced: 17 days ago
JSON representation
Converts OpenAPI 3.0 definitions to Plant UML text for visualisation of your API.
- Host: GitHub
- URL: https://github.com/davidmoten/openapi-to-plantuml
- Owner: davidmoten
- License: apache-2.0
- Created: 2021-02-17T03:47:43.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2024-10-23T17:24:59.000Z (21 days ago)
- Last Synced: 2024-10-24T01:13:27.782Z (20 days ago)
- Topics: java, online, openapi, openapi-documentation, openapi3, plantuml, uml-diagram
- Language: Java
- Homepage:
- Size: 6.13 MB
- Stars: 96
- Watchers: 4
- Forks: 18
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# openapi-to-plantuml
[](https://codecov.io/gh/davidmoten/openapi-to-plantuml)
[](https://maven-badges.herokuapp.com/maven-central/com.github.davidmoten/openapi-to-plantuml)
Java library to generate a [PlantUML](https://plantuml.com) Class Diagram (supplemented with path information) from an OpenAPI 3.0 definition (YAML or JSON).
Try it online [here](https://openapi-to-puml.davidmoten.org/prod/site/index.html).
**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](src/test/resources/openapi-example.yml):
## How to build
```bash
mvn clean install
```
## How to quickly convert your OpenAPI definition
The easiest thing to do is to use the [online converter](https://openapi-to-puml.davidmoten.org/prod/site/index.html). 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:
```xml
com.github.davidmoten
openapi-to-plantuml
VERSION_HERE
```
Or use the standalone *jar-with-dependencies* artifact from [Maven Central](https://search.maven.org/search?q=g:com.github.davidmoten%20AND%20a:openapi-to-plantuml) (or from the `target` directory if you have built the project locally):
### How to produce a single diagram
```bash
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`.
```bash
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
```bash
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
```java
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](src/docs/generated/examples.md).
[petstore-expanded.yml](src/test/resources/inputs/petstore-expanded.yml):
[bookstore.yml](src/test/resources/demos/bookstore.yml):
[ecommerce.yml](src/test/resources/demos/ecommerce.yml)
[news.yml](src/test/resources/demos/news.yml):
[strava.yml](src/test/resources/demos/strava.yml):
[twitter.yml](src/test/resources/demos/twitter.yml):
[ebay.yml](src/test/resources/demos/ebay.yml):
