nlohmann / swagger_to_uml Goto Github PK

Convert OpenAPI specifications (a.k.a. Swagger) to PlantUML diagrams

License: MIT License

Python 100.00%

swagger swagger-docs swagger2 plantuml plantuml-generator plantuml-diagrams openapi

swagger_to_uml's Introduction

Swagger to UML

A small pure Python script that converts OpenAPI specifications (a.k.a. Swagger) into Plant UML diagrams. The goal is not to replace existing documentation generators, but to complement them with a visual representation of the routes, models, and their relationships.

Example

To create a diagram from the petstore example, call the script with:

python swagger_to_uml.py petstore_example/swagger.json >petstore_example/swagger.puml

It will create the file petstore_example/swagger.puml which can then be translated into a PNG image with PlantUML with:

plantuml petstore_example/swagger.puml -tpng

Note you need to install Plant UML and Graphviz for this.

Installation

The script runs with Python 3 without any additional packages. Transforming PUML into vector graphics or other requires external tools however.

On macOS, the installation of the required tools with Homebrew is simple:

brew install plantuml graphviz

Contribute

The script is just a first proof-of-concept version. Issues and pull requests welcome!

Copyright

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

swagger_to_uml's People

Contributors

Stargazers

Watchers

Forkers

fenollp phfeustel 9bic jorgefdt lshinal pavelsimo alex-ppg home24 sayr777 asvitak thomassittig iorran dmivankov modred ccosentino daniel-sc pavel-zdenek remerle baileyrd ferasa22 jcoffi bellyfat jmslab70 mrfix93 kannanth gboue antback blaisep-vgs fpaterour rsassi sumittaneja kainepro hguidetti rodfersou josefsalyer ojengwa totolehero polats vinayasathyanarayana sindre-nistad gabrielf000 rongyj preetjadhav540 miromunich nyimbi simchucky vhorky leftxs sergekiryakov nad2000 jeethjoseph rnickle nbiastaunton arab69 ingridatmicrosoft python-repository-hub jischebeck jithin-m tonynv sunilkum84 fabricio-lobo kotenev ewaldertl pasihanhijarvi krishnasdb namuan pwgith kollaam mr-jz

swagger_to_uml's Issues

$ref not found and Yaml Extension

I get this error:

Traceback` (most recent call last):
  File "swagger_to_uml.py", line 380, in <module>
    sw = Swagger.from_file(input_file_name)
  File "swagger_to_uml.py", line 367, in from_file
    return Swagger.from_dict(loader(fd))
  File "swagger_to_uml.py", line 357, in from_dict
    definitions = [Definition.from_dict(name, definition) for name, definition in d.get('definitions',{}).items()]
  File "swagger_to_uml.py", line 357, in <listcomp>
    definitions = [Definition.from_dict(name, definition) for name, definition in d.get('definitions',{}).items()]
  File "swagger_to_uml.py", line 197, in from_dict
    required=property_name in d.get('required', [])
  File "swagger_to_uml.py", line 103, in from_dict
    items = resolve_ref(type_dict['items']['$ref'])
KeyError: '$ref'

Fixed:

c103
<                 items = resolve_ref(type_dict['items']['$ref']) if '$ref' in type_dict['items'] else None
c364
<         if filename.endswith('.yml') or filename.endswith('.yaml'):

Sorry cant do pull req due to ... policy

Update README Please

Hello, I really appreciate this tool. Since the python script was converted to shell script with setup it no longer works for me or I do not understand how to use it. I reverted to older version and was able to use it with the script. When you have time can you please update the README to explain how to use this with the new shell script. Thank you!

allOf not handled in Items

Hello,

I need to define property UnitGameSystem.profiles with an array of multiple type of object ProfileXXX whish are inherited of object Profile

...
  UnitGameSystem:
    properties:
      id:
        type: string
      name:
        type: string
      profiles:
        items:
          allOf:
            - $ref: '#/definitions/ProfileAOS4'
            - $ref: '#/definitions/ProfileWFB9'
            - $ref: '#/definitions/ProfileWFB12'
            - $ref: '#/definitions/ProfileWHQ'
            - $ref: '#/definitions/ProfileT9A12'
        type: array
...

I have an error for this definition

d:\PROJECTS\swagger_to_uml>python swagger_to_uml.py fantasy-battle-db.swagger.json > fantasy-battle-db.puml
Traceback (most recent call last):
  File "d:\PROJECTS\swagger_to_uml\swagger_to_uml.py", line 380, in <module>
    sw = Swagger.from_file(input_file_name)
  File "d:\PROJECTS\swagger_to_uml\swagger_to_uml.py", line 367, in from_file
    return Swagger.from_dict(loader(fd))
  File "d:\PROJECTS\swagger_to_uml\swagger_to_uml.py", line 356, in from_dict
    definitions = [Definition.from_dict(name, definition) for name, definition in d.get('definitions',{}).items()]
  File "d:\PROJECTS\swagger_to_uml\swagger_to_uml.py", line 356, in <listcomp>
    definitions = [Definition.from_dict(name, definition) for name, definition in d.get('definitions',{}).items()]
  File "d:\PROJECTS\swagger_to_uml\swagger_to_uml.py", line 193, in from_dict
    properties.append(Property.from_dict(
  File "d:\PROJECTS\swagger_to_uml\swagger_to_uml.py", line 102, in from_dict
    items = resolve_ref(type_dict['items']['$ref'])
KeyError: '$ref'

full json is : fantasy-battle-db.swagger.json.txt

Thank's you

Handling allOf for Dog and Cat types of Pet

Extended Pet example to include Cat and Dog using allOf example from here: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md

Get the following error:

`python swagger_to_uml.py swagger.json > swagger.puml
required key "type" not found in dictionary {"description": "A representation of a cat", "allOf": [{"$ref": "#/definitions/Pet"}, {"type": "object", "properties": {"huntingSkill": {"type": "string", "description": "The measured skill for hunting", "default": "lazy", "enum": ["clueless", "lazy", "adventurous", "aggressive"]}}, "required": ["huntingSkill"]}]}
Traceback (most recent call last):
File "swagger_to_uml.py", line 380, in
sw = Swagger.from_file(input_file_name)
File "swagger_to_uml.py", line 367, in from_file
return Swagger.from_dict(loader(fd))
File "swagger_to_uml.py", line 357, in from_dict
definitions = [Definition.from_dict(name, definition) for name, definition in d.get('definitions',{}).items()]
File "swagger_to_uml.py", line 357, in
definitions = [Definition.from_dict(name, definition) for name, definition in d.get('definitions',{}).items()]
File "swagger_to_uml.py", line 204, in from_dict
type=d['type'],
KeyError: 'type'

Modified swagger attached

swagger.json.txt

Syntax error

I get this syntax error in plantuml :

Do you have an idea how to solve it ?

Best regards
Jean Marc

Does not follow html $ref

Path is replaced with $ref to an openapi yaml stored html.

Example:
paths:
/:
$ref: 'https://artifactory.mycompany.com/artifactory/maven/com/apis/common/0.1.0-20210924151918/common-0.1.0-20210924151918.yaml#/paths/New'
/instances:
$ref: 'https://artifactory.mycompany.com/artifactory/maven/com/apis/common/0.1.0-20210924151918/common-0.1.0-20210924151918.yaml#/paths/GetInstanceIds'

swagger_to_uml throws the following error
Traceback (most recent call last):
File "C:/Users/212708371/Documents/Gitlab/build-util/swagger_to_uml.py", line 367, in from_file
return Swagger.from_dict(loader(fd))
File "C:/Users/212708371/Documents/Gitlab/build-util/swagger_to_uml.py", line 357, in from_dict
paths = [Path.from_dict(d, path_name, path) for path_name, path in d['paths'].items()]
File "C:/Users/212708371/Documents/Gitlab/build-util/swagger_to_uml.py", line 357, in
paths = [Path.from_dict(d, path_name, path) for path_name, path in d['paths'].items()]
File "C:/Users/212708371/Documents/Gitlab/build-util/swagger_to_uml.py", line 336, in from_dict
operations=[Operation.from_dict(whole, path_name, t, op, parameters) for t, op in d.items() if t not in ['parameters', 'summary', 'description']]
File "C:/Users/212708371/Documents/Gitlab/build-util/swagger_to_uml.py", line 336, in
operations=[Operation.from_dict(whole, path_name, t, op, parameters) for t, op in d.items() if t not in ['parameters', 'summary', 'description']]
File "C:/Users/212708371/Documents/Gitlab/build-util/swagger_to_uml.py", line 286, in from_dict
summary=d.get('summary'),

I am assuming that it would also throw errors for my Parameters and Schemas which also reference html but it fails before getting to those

Error: required key "type" not found in dictionary

I successfully generated a diagram for the petstore API, but failed on this file:
https://consumerdatastandardsaustralia.github.io/standards/includes/swagger/cds_full.json

The file passes a validation test, but I can't rule out a problem with the file (or my local setup).

error.txt

JSON Schema Support

Hi I was used to use this good tool some year ago to fully document my APIs

What about JSON Schema support ?

masking of invalid chars in puml

If there are plus chars in the name of an entity, they are not correctly masked.

workaround:

sed -i 's#\([^ ]*[+][^ ]*\)#"\1"#g' swagger.puml

before image creation

Python erros

Hi
I tried to run python part of processing calling

python swagger_to_uml.py petstore_example/swagger.json >petstore_example/swagger.puml

and i got message like this

  "File "swagger_to_uml.py", line 376
    print(sw.uml, end='', flush=True)"

Do you have idea what I'm doing wrong ? :)

Thanks for info :-)

Best regards

PyPI

This tool doesnt appear to be on PyPI yet.