Add new output style for API overviews with PlantUML

Author: RobertoPrevato

CHANGELOG.md

@@ -5,6 +5,10 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.1] - 2022-??-??
+- Adds a new output style, to provide an overview of the API endpoints with
+  PlantUML
+
 ## [1.0.0] - 2022-04-20 :sparkles:
 - Adds features and a CLI to generate artifacts from OpenAPI Documentation
   files (markdown for MkDocs and PyMdown extensions, PlantUML class diagrams

README.md

@@ -43,7 +43,7 @@ To generate output for [MkDocs](https://www.mkdocs.org) and [PyMdown extentions]
 oad gen-docs -s example1-openapi.json -d output.md
 ```
 
-![Example MkDocs documentation](./docs/example-1.png)
+![Example MkDocs documentation](https://gist.githubusercontent.com/RobertoPrevato/38a0598b515a2f7257c614938843b99b/raw/06e157c4f49e27a7e488d72d36d199194e28e952/oad-example-1.png)
 
 _Example of MkDocs documentation generated using [Neoteroi/mkdocs-plugins](https://github.com/Neoteroi/mkdocs-plugins)._
 
@@ -56,10 +56,23 @@ diagram](https://plantuml.com/class-diagram) of the components schemas:
 oad gen-docs -s source-openapi.json -d schemas.wsd --style "PLANTUML_SCHEMAS"
 ```
 
-![Example schemas](./docs/example-schemas.png)
+![Example schemas](https://gist.githubusercontent.com/RobertoPrevato/38a0598b515a2f7257c614938843b99b/raw/06e157c4f49e27a7e488d72d36d199194e28e952/oad-example-schemas.png)
 
 _Example of PlantUML diagram generated from components schemas._
 
+---
+
+To generate a [PlantUML](https://plantuml.com) [class
+diagram](https://plantuml.com/class-diagram) with an overview of API endpoints:
+
+```bash
+oad gen-docs -s source-openapi.json -d schemas.wsd --style "PLANTUML_API"
+```
+
+![Example api overview](https://gist.githubusercontent.com/RobertoPrevato/38a0598b515a2f7257c614938843b99b/raw/3c6fdf85f6dd1a99ba1bd0486707dff557ff4ac4/oad-api-example.png)
+
+_Example of PlantUML diagram generated from path items._
+
 ### Goals
 
 * Provide an API to generate OpenAPI Documentation files.
@@ -94,6 +107,7 @@ _Example of PlantUML diagram generated from components schemas._
 | MARKDOWN         | 2         | Basic Markdown.                              |
 | HTML             | 3         | Plain HTML _(planned, not yet implemented)_. |
 | PLANTUML_SCHEMAS | 100       | PlantUML schema for components schemas.      |
+| PLANTUML_API     | 101       | PlantUML schema for API endpoints.           |
 
 ### Supported sources for OpenAPI Documentation
 

docs/example-1.png

@@ -39,7 +39,10 @@ class OutputStyle(Enum):
     """Basic Markdown"""
 
     PLANTUML_SCHEMAS = 100
-    """PlantUML schema for components schemas."""
+    """PlantUML class diagram for components schemas."""
+
+    PLANTUML_API = 101
+    """PlantUML diagram of the API with request and response bodies."""
 
 
 class PackageLoadingError(ValueError):

docs/example-schemas.png

@@ -0,0 +1,4 @@
+# Views to generate PlantUML API schema
+
+This folder contains views to generate a diagram of the API with request
+/ response bodies for [PlantUML](https://plantuml.com).

openapidocs/mk/jinja.py

@@ -0,0 +1,22 @@
+@startuml "API schema"
+/'
+This diagram has been generated by essentials-openapi
+https://github.com/Neoteroi/essentials-openapi
+
+Most likely, it is not desirable to edit this file by hand!
+'/
+top to bottom direction
+hide empty members
+
+{% for tag, operations in handler.get_operations().items() %}
+
+interface "{{tag}} API" as {{tag | lower}}_api {
+{%- for path, definition in operations %}
+{%- for http_method, operation in definition.items() %}
+    + **{{http_method.upper()}}** {{path}}
+    {%- endfor %}
+    {%- endfor %}
+}
+{% endfor %}
+
+@enduml

openapidocs/mk/v3/views_plantuml_api/README.md

@@ -0,0 +1,26 @@
+{%- if is_reference(schema) -%}
+{%- with type_name = schema["$ref"].replace("#/components/schemas/", "") -%}
+{{type_name}}
+{%- endwith -%}
+{%- endif -%}
+
+{%- if schema.type -%}
+{%- with type_name = schema["type"], nullable = schema.get("nullable") -%}
+{# Scalar types #}
+{%- if type_name in scalar_types -%}
+{{type_name}}
+{%- if schema.format -%}
+({{schema.format}})
+{%- endif -%}
+{%- if nullable %} | null{%- endif -%}
+{%- endif -%}
+{%- if type_name == "array" -%}
+{%- with schema = schema["items"] -%}
+Array of {% include "partial/schema-repr.html" -%}
+{%- endwith -%}
+{%- endif -%}
+{%- if type_name == "null" -%}
+null
+{%- endif -%}
+{%- endwith -%}
+{%- endif -%}

openapidocs/mk/v3/views_plantuml_api/layout.html

@@ -6,6 +6,7 @@
 Most likely, it is not desirable to edit this file by hand!
 '/
 top to bottom direction
+hide empty members
 
 {% for name, definition in handler.get_schemas() %}
 class {{name}} {

openapidocs/mk/v3/views_plantuml_api/partial/schema-repr.html

@@ -0,0 +1,69 @@
+@startuml "API schema"
+/'
+This diagram has been generated by essentials-openapi
+https://github.com/Neoteroi/essentials-openapi
+
+Most likely, it is not desirable to edit this file by hand!
+'/
+top to bottom direction
+hide empty members
+
+
+
+interface "Blobs API" as blobs_api {
+    + **POST** /api/blobs/initialize-upload
+}
+
+
+interface "Categories API" as categories_api {
+    + **GET** /api/categories
+}
+
+
+interface "Countries API" as countries_api {
+    + **GET** /api/countries
+    + **GET** /api/system-countries
+}
+
+
+interface "Downloads API" as downloads_api {
+    + **GET** /api/downloads
+}
+
+
+interface "Health API" as health_api {
+    + **GET** /api/health
+}
+
+
+interface "Professionals API" as professionals_api {
+    + **GET** /api/pro/own-context
+}
+
+
+interface "Info API" as info_api {
+    + **GET** /api/info
+}
+
+
+interface "Releases API" as releases_api {
+    + **GET** /api/releases/{releaseId}
+    + **DELETE** /api/releases/{releaseId}
+    + **PATCH** /api/releases/{releaseId}
+    + **GET** /api/releases
+    + **POST** /api/releases
+    + **GET** /api/current-releases
+    + **GET** /api/orgs/current-releases
+    + **GET** /api/releases/{releaseId}/history
+    + **GET** /api/releases/{releaseId}/file/{nodeId}
+    + **GET** /api/releases/{releaseId}/file/{nodeId}/downloads
+    + **PUT** /api/releases/{releaseId}/files
+    + **DELETE** /api/releases/{releaseId}/files
+    + **PUT** /api/releases/{releaseId}/orgs
+    + **DELETE** /api/releases/{releaseId}/orgs
+    + **POST** /api/releases/{releaseId}/clone
+    + **POST** /api/releases/{releaseId}/publish
+}
+
+
+@enduml