[](https://pypi.python.org/pypi/essentials-openapi)
[](https://github.com/neoteroi/essentials-openapi)
[](https://github.com/neoteroi/essentials-openapi/blob/main/LICENSE)
[](https://codecov.io/gh/Neoteroi/essentials-openapi)
# essentials-openapi
Classes to generate [OpenAPI Documentation](https://swagger.io/specification/)
v3 and v2, in JSON and YAML, and to generate other kinds of documents from
OpenAPI Documentation files.
```bash
pip install essentials-openapi
```
To install with dependencies to generate other kinds of artifacts from source
OpenAPI Documentation files:
```bash
pip install essentials-openapi[full]
```
## Useful links
* https://swagger.io/specification/
* https://editor.swagger.io
## Usage
This library has been originally created to implement generation of OpenAPI Documentation
in the [`BlackSheep` web framework](https://github.com/RobertoPrevato/BlackSheep).
However, this package is abstracted from that web framework and can be reused for other
applications. Today this library also offers functions to generate documentation from
source OpenAPI Documentation files.
## Features to generate artifacts from Open API Documentation
These require the full package: install it using `pip install essentials-openapi[full]`.
To generate output for [MkDocs](https://www.mkdocs.org) and [PyMdown extentions](https://facelessuser.github.io/pymdown-extensions/):
```bash
oad gen-docs -s example1-openapi.json -d output.md
```
_Example of MkDocs documentation generated using [Neoteroi/mkdocs-plugins](https://github.com/Neoteroi/mkdocs-plugins)._
---
To generate a [PlantUML](https://plantuml.com) [class
diagram](https://plantuml.com/class-diagram) of the components schemas:
```bash
oad gen-docs -s source-openapi.json -d schemas.wsd --style "PLANTUML_SCHEMAS"
```
_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 of PlantUML diagram generated from path items._
### Goals
* Provide an API to generate OpenAPI Documentation files.
* Providing functions to handle OpenAPI Documentation, like those to generate
other kinds of documentation from source OpenAPI Documentation files.
* Support enough features to be useful for the most common API scenarios,
especially for OAD files that are generated automatically from web frameworks.
### Non-Goals
* To implement the whole OAD Specification.
* For the features that generate artifacts: OpenAPI Documentation files are
**supposed to be coming from trusted sources**. Trying to handle source files
from untrusted sources and potentially causing HTML injection is out of the
scope of this library.
## Limitations
* Partial support for Parameter properties: `style`, `allow_reserved`, `explode` are not
handled.
* Doesn't implement validation of values, currently it is only concerned in generating
code from a higher level API (it might be extended in the future with classes for
validation).
* The features to generate artifacts from OpenAPI Documentation currently support only
Version 3 of the specification.
### Styles
| Style | Int value | Description |
| ---------------- | --------- | -------------------------------------------- |
| MKDOCS | 1 | Markdown for MkDocs and PyMdown extensions. |
| 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
| Source | Example |
| ------------------------------ | ---------------------------------------------------- |
| YAML file | `./docs/swagger.yaml` |
| JSON file | `./docs/swagger.json` |
| URL returning YAML on HTTP GET | `https://example-domain.net/swagger/v1/swagger.yaml` |
| URL returning JSON on HTTP GET | `https://example-domain.net/swagger/v1/swagger.json` |
Raw data
{
"_id": null,
"home_page": null,
"name": "essentials-openapi",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "Markdown, api, docs, documentation, json, openapi, swagger, v2, v3, yaml",
"author": null,
"author_email": "Roberto Prevato <roberto.prevato@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/54/4a/7379c77a0d3ee316a1f2ff3218942c2e272249a2ec9548bbb0ee5bbce25f/essentials_openapi-1.2.1.tar.gz",
"platform": null,
"description": "\n[](https://pypi.python.org/pypi/essentials-openapi)\n[](https://github.com/neoteroi/essentials-openapi)\n[](https://github.com/neoteroi/essentials-openapi/blob/main/LICENSE)\n[](https://codecov.io/gh/Neoteroi/essentials-openapi)\n\n# essentials-openapi\n\nClasses to generate [OpenAPI Documentation](https://swagger.io/specification/)\nv3 and v2, in JSON and YAML, and to generate other kinds of documents from\nOpenAPI Documentation files.\n\n```bash\npip install essentials-openapi\n```\n\nTo install with dependencies to generate other kinds of artifacts from source\nOpenAPI Documentation files:\n\n```bash\npip install essentials-openapi[full]\n```\n\n## Useful links\n\n* https://swagger.io/specification/\n* https://editor.swagger.io\n\n## Usage\nThis library has been originally created to implement generation of OpenAPI Documentation\nin the [`BlackSheep` web framework](https://github.com/RobertoPrevato/BlackSheep).\nHowever, this package is abstracted from that web framework and can be reused for other\napplications. Today this library also offers functions to generate documentation from\nsource OpenAPI Documentation files.\n\n## Features to generate artifacts from Open API Documentation\n\nThese require the full package: install it using `pip install essentials-openapi[full]`.\n\nTo generate output for [MkDocs](https://www.mkdocs.org) and [PyMdown extentions](https://facelessuser.github.io/pymdown-extensions/):\n\n```bash\noad gen-docs -s example1-openapi.json -d output.md\n```\n\n\n\n_Example of MkDocs documentation generated using [Neoteroi/mkdocs-plugins](https://github.com/Neoteroi/mkdocs-plugins)._\n\n---\n\nTo generate a [PlantUML](https://plantuml.com) [class\ndiagram](https://plantuml.com/class-diagram) of the components schemas:\n\n```bash\noad gen-docs -s source-openapi.json -d schemas.wsd --style \"PLANTUML_SCHEMAS\"\n```\n\n\n\n_Example of PlantUML diagram generated from components schemas._\n\n---\n\nTo generate a [PlantUML](https://plantuml.com) [class\ndiagram](https://plantuml.com/class-diagram) with an overview of API endpoints:\n\n```bash\noad gen-docs -s source-openapi.json -d schemas.wsd --style \"PLANTUML_API\"\n```\n\n\n\n_Example of PlantUML diagram generated from path items._\n\n### Goals\n\n* Provide an API to generate OpenAPI Documentation files.\n* Providing functions to handle OpenAPI Documentation, like those to generate\n other kinds of documentation from source OpenAPI Documentation files.\n* Support enough features to be useful for the most common API scenarios,\n especially for OAD files that are generated automatically from web frameworks.\n\n### Non-Goals\n\n* To implement the whole OAD Specification.\n* For the features that generate artifacts: OpenAPI Documentation files are\n **supposed to be coming from trusted sources**. Trying to handle source files\n from untrusted sources and potentially causing HTML injection is out of the\n scope of this library.\n\n## Limitations\n\n* Partial support for Parameter properties: `style`, `allow_reserved`, `explode` are not\n handled.\n* Doesn't implement validation of values, currently it is only concerned in generating\n code from a higher level API (it might be extended in the future with classes for\n validation).\n* The features to generate artifacts from OpenAPI Documentation currently support only\n Version 3 of the specification.\n\n### Styles\n\n| Style | Int value | Description |\n| ---------------- | --------- | -------------------------------------------- |\n| MKDOCS | 1 | Markdown for MkDocs and PyMdown extensions. |\n| MARKDOWN | 2 | Basic Markdown. |\n| HTML | 3 | Plain HTML _(planned, not yet implemented)_. |\n| PLANTUML_SCHEMAS | 100 | PlantUML schema for components schemas. |\n| PLANTUML_API | 101 | PlantUML schema for API endpoints. |\n\n### Supported sources for OpenAPI Documentation\n\n| Source | Example |\n| ------------------------------ | ---------------------------------------------------- |\n| YAML file | `./docs/swagger.yaml` |\n| JSON file | `./docs/swagger.json` |\n| URL returning YAML on HTTP GET | `https://example-domain.net/swagger/v1/swagger.yaml` |\n| URL returning JSON on HTTP GET | `https://example-domain.net/swagger/v1/swagger.json` |\n",
"bugtrack_url": null,
"license": null,
"summary": "Classes to generate OpenAPI Documentation v3 and v2, in JSON and YAML.",
"version": "1.2.1",
"project_urls": {
"Bug Tracker": "https://github.com/Neoteroi/essentials-openapi/issues",
"Homepage": "https://github.com/Neoteroi/essentials-openapi"
},
"split_keywords": [
"markdown",
" api",
" docs",
" documentation",
" json",
" openapi",
" swagger",
" v2",
" v3",
" yaml"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "10be2963872265498da09800dc730a17a51a1c8f79c16cb29d8402425c21a96e",
"md5": "ec9d870800f9cbe84ffc1b40d99298df",
"sha256": "d0085cde3ceaa25e6fc4983d8372ac0185909e3fa2791f498280379bb3c86c62"
},
"downloads": -1,
"filename": "essentials_openapi-1.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ec9d870800f9cbe84ffc1b40d99298df",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 54167,
"upload_time": "2025-07-30T17:13:59",
"upload_time_iso_8601": "2025-07-30T17:13:59.107229Z",
"url": "https://files.pythonhosted.org/packages/10/be/2963872265498da09800dc730a17a51a1c8f79c16cb29d8402425c21a96e/essentials_openapi-1.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "544a7379c77a0d3ee316a1f2ff3218942c2e272249a2ec9548bbb0ee5bbce25f",
"md5": "93c12a6aaf4b309f4cd99642177efd6f",
"sha256": "70b06d80a8d9cb7634b702903cfe8fcfc48e6fc054e744eab514bb7bc37f00c9"
},
"downloads": -1,
"filename": "essentials_openapi-1.2.1.tar.gz",
"has_sig": false,
"md5_digest": "93c12a6aaf4b309f4cd99642177efd6f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 33305,
"upload_time": "2025-07-30T17:14:00",
"upload_time_iso_8601": "2025-07-30T17:14:00.345773Z",
"url": "https://files.pythonhosted.org/packages/54/4a/7379c77a0d3ee316a1f2ff3218942c2e272249a2ec9548bbb0ee5bbce25f/essentials_openapi-1.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-30 17:14:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Neoteroi",
"github_project": "essentials-openapi",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "annotated-types",
"specs": [
[
"==",
"0.6.0"
]
]
},
{
"name": "anyio",
"specs": [
[
"==",
"4.0.0"
]
]
},
{
"name": "black",
"specs": [
[
"==",
"23.11.0"
]
]
},
{
"name": "blinker",
"specs": [
[
"==",
"1.7.0"
]
]
},
{
"name": "certifi",
"specs": [
[
"==",
"2023.11.17"
]
]
},
{
"name": "click",
"specs": [
[
"==",
"8.1.7"
]
]
},
{
"name": "coverage",
"specs": [
[
"==",
"7.3.2"
]
]
},
{
"name": "essentials",
"specs": [
[
"==",
"1.1.5"
]
]
},
{
"name": "flake8",
"specs": [
[
"==",
"6.1.0"
]
]
},
{
"name": "Flask",
"specs": [
[
"==",
"3.0.0"
]
]
},
{
"name": "h11",
"specs": [
[
"==",
"0.14.0"
]
]
},
{
"name": "httpcore",
"specs": [
[
"==",
"1.0.2"
]
]
},
{
"name": "httpx",
"specs": [
[
"==",
"0.25.1"
]
]
},
{
"name": "idna",
"specs": [
[
"==",
"3.4"
]
]
},
{
"name": "iniconfig",
"specs": [
[
"==",
"2.0.0"
]
]
},
{
"name": "isort",
"specs": [
[
"==",
"5.12.0"
]
]
},
{
"name": "itsdangerous",
"specs": [
[
"==",
"2.1.2"
]
]
},
{
"name": "Jinja2",
"specs": [
[
"==",
"3.1.2"
]
]
},
{
"name": "markdown-it-py",
"specs": [
[
"==",
"3.0.0"
]
]
},
{
"name": "MarkupSafe",
"specs": [
[
"==",
"3.0.1"
]
]
},
{
"name": "mccabe",
"specs": [
[
"==",
"0.7.0"
]
]
},
{
"name": "mdurl",
"specs": [
[
"==",
"0.1.2"
]
]
},
{
"name": "mypy-extensions",
"specs": [
[
"==",
"1.0.0"
]
]
},
{
"name": "packaging",
"specs": [
[
"==",
"23.2"
]
]
},
{
"name": "pathspec",
"specs": [
[
"==",
"0.11.2"
]
]
},
{
"name": "platformdirs",
"specs": [
[
"==",
"4.0.0"
]
]
},
{
"name": "pluggy",
"specs": [
[
"==",
"1.3.0"
]
]
},
{
"name": "pycodestyle",
"specs": [
[
"==",
"2.11.1"
]
]
},
{
"name": "pydantic",
"specs": [
[
"==",
"2.10.6"
]
]
},
{
"name": "pyflakes",
"specs": [
[
"==",
"3.1.0"
]
]
},
{
"name": "Pygments",
"specs": [
[
"==",
"2.17.1"
]
]
},
{
"name": "pytest",
"specs": [
[
"==",
"7.4.3"
]
]
},
{
"name": "pytest-cov",
"specs": [
[
"==",
"4.1.0"
]
]
},
{
"name": "PyYAML",
"specs": [
[
"==",
"6.0.1"
]
]
},
{
"name": "rich",
"specs": [
[
"==",
"13.7.0"
]
]
},
{
"name": "sniffio",
"specs": [
[
"==",
"1.3.0"
]
]
},
{
"name": "typing_extensions",
"specs": [
[
">=",
"4.8.0"
]
]
},
{
"name": "Werkzeug",
"specs": [
[
"==",
"3.0.1"
]
]
}
],
"lcname": "essentials-openapi"
}
JSON
