Classes to generate OpenAPI Documentation v3 and v2, in JSON and YAML.
Project description
essentials-openapi
Classes to generate OpenAPI Documentation v3 and v2, in JSON and YAML, and to generate other kinds of documents from OpenAPI Documentation files.
pip install essentials-openapi
To install with dependencies to generate other kinds of artifacts from source OpenAPI Documentation files:
pip install essentials-openapi[full]
Useful links
Usage
This library has been originally created to implement generation of OpenAPI Documentation
in the BlackSheep
web framework.
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 and PyMdown extentions:
oad gen-docs -s example1-openapi.json -d output.md
Example of MkDocs documentation generated using Neoteroi/mkdocs-plugins.
To generate a PlantUML class diagram of the components schemas:
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 class diagram with an overview of API endpoints:
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 |
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file essentials_openapi-1.0.9.tar.gz
.
File metadata
- Download URL: essentials_openapi-1.0.9.tar.gz
- Upload date:
- Size: 26.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.11.6
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | ebc46aac41c0b917a658f77caaa0ca93a6e4a4519de8a272f82c1538ccd5619f |
|
MD5 | 5b93a394ed145db420e805ce413ec7c8 |
|
BLAKE2b-256 | acd14436d49a6394daade8bd075e255b8940228a8359bcac40f46ddc8d3ae0ba |
File details
Details for the file essentials_openapi-1.0.9-py3-none-any.whl
.
File metadata
- Download URL: essentials_openapi-1.0.9-py3-none-any.whl
- Upload date:
- Size: 48.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.11.6
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1431e98ef0a442f1919fd9833385bf44d832c355fd05919dc06d43d4da0f8ef4 |
|
MD5 | 5d8f77826e1e187fb53bbb47d68c19ca |
|
BLAKE2b-256 | dfba71f33232e10c34240ecc30582129b57e807c0e5b6aa18ff1b3c50481fc7f |