[](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": "",
"name": "essentials-openapi",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "Markdown,api,docs,documentation,json,openapi,swagger,v2,v3,yaml",
"author": "",
"author_email": "Roberto Prevato <roberto.prevato@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/ac/d1/4436d49a6394daade8bd075e255b8940228a8359bcac40f46ddc8d3ae0ba/essentials_openapi-1.0.9.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": "",
"summary": "Classes to generate OpenAPI Documentation v3 and v2, in JSON and YAML.",
"version": "1.0.9",
"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": "",
"digests": {
"blake2b_256": "dfba71f33232e10c34240ecc30582129b57e807c0e5b6aa18ff1b3c50481fc7f",
"md5": "5d8f77826e1e187fb53bbb47d68c19ca",
"sha256": "1431e98ef0a442f1919fd9833385bf44d832c355fd05919dc06d43d4da0f8ef4"
},
"downloads": -1,
"filename": "essentials_openapi-1.0.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5d8f77826e1e187fb53bbb47d68c19ca",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 48148,
"upload_time": "2023-11-20T23:07:23",
"upload_time_iso_8601": "2023-11-20T23:07:23.517183Z",
"url": "https://files.pythonhosted.org/packages/df/ba/71f33232e10c34240ecc30582129b57e807c0e5b6aa18ff1b3c50481fc7f/essentials_openapi-1.0.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "acd14436d49a6394daade8bd075e255b8940228a8359bcac40f46ddc8d3ae0ba",
"md5": "5b93a394ed145db420e805ce413ec7c8",
"sha256": "ebc46aac41c0b917a658f77caaa0ca93a6e4a4519de8a272f82c1538ccd5619f"
},
"downloads": -1,
"filename": "essentials_openapi-1.0.9.tar.gz",
"has_sig": false,
"md5_digest": "5b93a394ed145db420e805ce413ec7c8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 26594,
"upload_time": "2023-11-20T23:07:25",
"upload_time_iso_8601": "2023-11-20T23:07:25.043473Z",
"url": "https://files.pythonhosted.org/packages/ac/d1/4436d49a6394daade8bd075e255b8940228a8359bcac40f46ddc8d3ae0ba/essentials_openapi-1.0.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-20 23:07:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Neoteroi",
"github_project": "essentials-openapi",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "essentials-openapi"
}
JSON
