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.

Sign up for GitHub

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

2022-01-01 One CLI several Open API files several supported output formats #29

Open
wants to merge 11 commits into
base: master
Choose a base branch
from
Open

2022-01-01 One CLI several Open API files several supported output formats #29

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
1bcea3a
Improved convertor and command line to support several files in one d…
tomer-sogo Jan 2, 2022
f5581d7
Updated to java 11 added developer
tomer-sogo Jan 2, 2022
0f989ce
Updated README.md pointing to relevant tests with more examples
tomer-sogo Jan 2, 2022
6951208
Updated README.md pointing to relevant tests with more examples
tomer-sogo Jan 2, 2022
d5950f6
Merge branch 'master' into 2021-01-01_CLI_Improvments
VRDate Jan 2, 2022
63a482d
Updated README.md pointing to relevant tests with more examples
tomer-sogo Jan 2, 2022
82cc1f9
Merge branch 'master' into 2022-01-01
VRDate Jan 23, 2022
4a1c0fa
Update pom.xml
VRDate Jan 23, 2022
2b4d1cc
Merge pull request #2 from Tomar-VRDate/2022-01-23
VRDate Jan 23, 2022
d92218c
Update pom.xml
VRDate Jan 23, 2022
e4fd2c6
Merge branch 'master' into 2022-01-01
VRDate Jan 23, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .idea/.gitignore
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

11 changes: 11 additions & 0 deletions .idea/aws.xml
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

65 changes: 65 additions & 0 deletions .idea/codeStyles/Project.xml
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

12 changes: 12 additions & 0 deletions .idea/misc.xml
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

8 changes: 8 additions & 0 deletions .idea/modules.xml
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 6 additions & 0 deletions .idea/vcs.xml
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

76 changes: 66 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,29 +1,33 @@
# openapi-to-plantuml

<a href="https://github.com/davidmoten/openapi-to-plantuml/actions/workflows/ci.yml"><img src="https://github.com/davidmoten/openapi-to-plantuml/actions/workflows/ci.yml/badge.svg"/></a><br/>
[![codecov](https://codecov.io/gh/davidmoten/openapi-to-plantuml/branch/main/graph/badge.svg)](https://codecov.io/gh/davidmoten/openapi-to-plantuml)<br/>
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.github.davidmoten/openapi-to-plantuml/badge.svg?style=flat)](https://maven-badges.herokuapp.com/maven-central/com.github.davidmoten/openapi-to-plantuml)<br/>

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).
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)
* Mixed types (*oneOf*, *anyOf*, *allOf*)
* Multiple levels of indirection (`$ref` -> `$ref` for example)
* Multiple response content types

**Status:** Released to Maven Central
**Status:** Released to Maven Central

**Limitations**

* Only handles internal references ("#/*"), that is the yaml file should be self-contained

**TODO**

* Model *Callbacks*
* Model *additionalProperties*

[openapi-example.yml](src/test/resources/openapi-example.yml):
[openapi-example.yml](src/test/resources/openapi-example.yml):

<img style="background-color:white" src="src/docs/openapi-example.svg"/>

Expand All @@ -35,31 +39,83 @@ 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`.
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
<dependency>
<groupId>com.github.davidmoten</groupId>
<artifactId>openapi-to-plantuml</artifactId>
<version>VERSION_HERE</version>
<version>2022-01-01-SNAPSHOT</version>
</dependency>
```

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):
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):

## Usage

Read com.github.davidmoten.oas3.puml.ConverterMainTest for more examples

```bash
Usage:
java -jar openapi-to-plantuml-all.jar <OPENAPI_YAML> <OUTPUT_DIRECTORY> <FILE_FORMAT>|<[FILE_FORMAT1, FILE_FORMAT1...]>
<OPENAPI_YAML> file or Directory containing *.yml or *.yaml files
<OUTPUT_DIRECTORY> output Directory
<FILE_FORMAT> optional file format default PUML and SVG only
or<[FILE_FORMAT1, FILE_FORMAT1...]> optional several file formats
surrounded by [delimited by comma and space ', ')] i.e. supported formats are:
[ATXT, BRAILLE_PNG, DEBUG, EPS, EPS_TEXT, LATEX, LATEX_NO_PREAMBLE, PNG, SVG, UTXT, VDX]
ATXT *.atxt text/plain
BRAILLE_PNG *.braille.png image/png
DEBUG *.debug text/plain
EPS *.eps application/postscript
EPS_TEXT *.eps.text.eps application/postscript
LATEX *.latex application/x-latex
LATEX_NO_PREAMBLE *.latex.no.preamble.latex application/x-latex
PNG *.png image/png
SVG *.svg image/svg+xml
UTXT *.utxt text/plain;charset=UTF-8
VDX *.vdx application/vnd.visio.xml
```

all demo files at src/test/resources/demo to target/converted-puml as PUML & SVG by default

```bash
java -jar target/openapi-to-plantuml-2022-01-01-SNAPSHOT-jar-with-dependencies.jar src/test/resources/demo target/converted-puml
```

all demo files at src/test/resources/demo to target/converted-puml as PUML, SVG & PNG

```bash
java -jar openapi-to-plantuml-VERSION_HERE-jar-with-dependencies.jar openapi.yaml PNG openapi.png
java -jar target/openapi-to-plantuml-2022-01-01-SNAPSHOT-jar-with-dependencies.jar src/test/resources/demo target/converted-puml "[SVG, PNG]"
```

## Usage

Read com.github.davidmoten.oas3.puml.DemoJavaTest for more examples All supported formats

```java
import com.github.davidmoten.oas3.puml.Converter;
Converter.writeOpenApiDirectoryFileToPumlAndTo(OPEN_API_DIRECTORY_FILE,
OUTPUT_DIRECTORY_FILE,
Converter.SUPPORTED_FORMATS);
```

String puml = Converter.openApiToPuml(openapi);
PUML, SVG & PNG

```java
Converter.writeOpenApiDirectoryFileToPumlAndTo(OPEN_API_DIRECTORY_FILE,
OUTPUT_DIRECTORY_FILE,
FileFormat.SVG,
FileFormat.PNG);
```

## Examples
Expand Down
82 changes: 82 additions & 0 deletions openapi-to-plantuml.eml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
<?xml version="1.0" encoding="UTF-8"?>
<component LANGUAGE_LEVEL="JDK_1_8" inheritJdk="true">
<output-test url="file://$MODULE_DIR$/target/test-classes"/>
<contentEntry url="file://$MODULE_DIR$">
<testFolder url="file://$MODULE_DIR$/src/test/java"/>
<excludeFolder url="file://$MODULE_DIR$/target"/>
</contentEntry>
<lib name="Maven: org.apache.logging.log4j:log4j-slf4j-impl:2.14.1" scope="TEST"/>
<lib name="Maven: org.apache.logging.log4j:log4j-api:2.14.1" scope="TEST"/>
<lib name="Maven: org.apache.logging.log4j:log4j-core:2.14.1" scope="TEST"/>
<lib name="Maven: junit:junit:4.13.2" scope="TEST"/>
<lib name="Maven: org.hamcrest:hamcrest-core:1.3" scope="TEST"/>
<lib name="Maven: com.github.davidmoten:junit-extras:0.4" scope="TEST"/>
<levels>
<level name="Maven: io.swagger.parser.v3:swagger-parser:2.0.28" value="project"/>
<level name="Maven: io.swagger.parser.v3:swagger-parser-v2-converter:2.0.28" value="project"/>
<level name="Maven: io.swagger:swagger-core:1.6.3" value="project"/>
<level name="Maven: org.apache.commons:commons-lang3:3.2.1" value="project"/>
<level name="Maven: io.swagger:swagger-models:1.6.3" value="project"/>
<level name="Maven: io.swagger:swagger-annotations:1.6.3" value="project"/>
<level name="Maven: com.google.guava:guava:27.0.1-android" value="project"/>
<level name="Maven: com.google.guava:failureaccess:1.0.1" value="project"/>
<level name="Maven: com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava" value="project"/>
<level name="Maven: org.checkerframework:checker-compat-qual:2.5.2" value="project"/>
<level name="Maven: com.google.errorprone:error_prone_annotations:2.2.0" value="project"/>
<level name="Maven: com.google.j2objc:j2objc-annotations:1.1" value="project"/>
<level name="Maven: org.codehaus.mojo:animal-sniffer-annotations:1.17" value="project"/>
<level name="Maven: javax.validation:validation-api:1.1.0.Final" value="project"/>
<level name="Maven: io.swagger:swagger-parser:1.0.56" value="project"/>
<level name="Maven: io.swagger:swagger-compat-spec-parser:1.0.56" value="project"/>
<level name="Maven: com.github.java-json-tools:json-schema-validator:2.2.14" value="project"/>
<level name="Maven: com.github.java-json-tools:jackson-coreutils-equivalence:1.0" value="project"/>
<level name="Maven: com.github.java-json-tools:json-schema-core:1.2.14" value="project"/>
<level name="Maven: com.github.java-json-tools:uri-template:0.10" value="project"/>
<level name="Maven: org.mozilla:rhino:1.7.7.2" value="project"/>
<level name="Maven: com.sun.mail:mailapi:1.6.2" value="project"/>
<level name="Maven: joda-time:joda-time:2.10.5" value="project"/>
<level name="Maven: com.googlecode.libphonenumber:libphonenumber:8.11.1" value="project"/>
<level name="Maven: net.sf.jopt-simple:jopt-simple:5.0.4" value="project"/>
<level name="Maven: com.github.java-json-tools:json-patch:1.13" value="project"/>
<level name="Maven: com.github.java-json-tools:msg-simple:1.2" value="project"/>
<level name="Maven: com.github.java-json-tools:btf:1.3" value="project"/>
<level name="Maven: com.github.java-json-tools:jackson-coreutils:2.0" value="project"/>
<level name="Maven: org.apache.httpcomponents:httpclient:4.5.13" value="project"/>
<level name="Maven: org.apache.httpcomponents:httpcore:4.4.13" value="project"/>
<level name="Maven: commons-logging:commons-logging:1.2" value="project"/>
<level name="Maven: commons-codec:commons-codec:1.11" value="project"/>
<level name="Maven: io.swagger.core.v3:swagger-models:2.1.11" value="project"/>
<level name="Maven: io.swagger.parser.v3:swagger-parser-core:2.0.28" value="project"/>
<level name="Maven: io.swagger.parser.v3:swagger-parser-v3:2.0.28" value="project"/>
<level name="Maven: io.swagger.core.v3:swagger-core:2.1.11" value="project"/>
<level name="Maven: jakarta.xml.bind:jakarta.xml.bind-api:2.3.2" value="project"/>
<level name="Maven: jakarta.activation:jakarta.activation-api:1.2.1" value="project"/>
<level name="Maven: com.fasterxml.jackson.datatype:jackson-datatype-jsr310:2.12.1" value="project"/>
<level name="Maven: io.swagger.core.v3:swagger-annotations:2.1.11" value="project"/>
<level name="Maven: jakarta.validation:jakarta.validation-api:2.0.2" value="project"/>
<level name="Maven: com.fasterxml.jackson.core:jackson-annotations:2.12.1" value="project"/>
<level name="Maven: com.fasterxml.jackson.core:jackson-databind:2.12.1" value="project"/>
<level name="Maven: com.fasterxml.jackson.core:jackson-core:2.12.1" value="project"/>
<level name="Maven: com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:2.12.1" value="project"/>
<level name="Maven: org.yaml:snakeyaml:1.27" value="project"/>
<level name="Maven: commons-io:commons-io:2.11.0" value="project"/>
<level name="Maven: com.github.davidmoten:guava-mini:0.1.4" value="project"/>
<level name="Maven: org.slf4j:slf4j-api:1.7.30" value="project"/>
<level name="Maven: net.sourceforge.plantuml:plantuml:1.2021.16" value="project"/>
<level name="Maven: guru.nidi:graphviz-java:0.18.1" value="project"/>
<level name="Maven: org.webjars.npm:viz.js-graphviz-java:2.1.3" value="project"/>
<level name="Maven: guru.nidi.com.kitfox:svgSalamander:1.1.3" value="project"/>
<level name="Maven: net.arnx:nashorn-promise:0.1.1" value="project"/>
<level name="Maven: org.apache.commons:commons-exec:1.3" value="project"/>
<level name="Maven: com.google.code.findbugs:jsr305:3.0.2" value="project"/>
<level name="Maven: org.slf4j:jcl-over-slf4j:1.7.30" value="project"/>
<level name="Maven: org.slf4j:jul-to-slf4j:1.7.30" value="project"/>
<level name="Maven: guru.nidi.com.eclipsesource.j2v8:j2v8_win32_x86_64:4.6.0" value="project"/>
<level name="Maven: org.apache.logging.log4j:log4j-slf4j-impl:2.14.1" value="project"/>
<level name="Maven: org.apache.logging.log4j:log4j-api:2.14.1" value="project"/>
<level name="Maven: org.apache.logging.log4j:log4j-core:2.14.1" value="project"/>
<level name="Maven: junit:junit:4.13.2" value="project"/>
<level name="Maven: org.hamcrest:hamcrest-core:1.3" value="project"/>
<level name="Maven: com.github.davidmoten:junit-extras:0.4" value="project"/>
</levels>
</component>
Loading