Skip to main content

Classes to generate OpenAPI Documentation v3 and v2, in JSON and YAML.

Project description

Build pypi versions license codecov

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 MkDocs documentation

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 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 api overview

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


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

essentials_openapi-1.0.9.tar.gz (26.6 kB view details)

Uploaded Source

Built Distribution

essentials_openapi-1.0.9-py3-none-any.whl (48.1 kB view details)

Uploaded Python 3

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

Hashes for essentials_openapi-1.0.9.tar.gz
Algorithm Hash digest
SHA256 ebc46aac41c0b917a658f77caaa0ca93a6e4a4519de8a272f82c1538ccd5619f
MD5 5b93a394ed145db420e805ce413ec7c8
BLAKE2b-256 acd14436d49a6394daade8bd075e255b8940228a8359bcac40f46ddc8d3ae0ba

See more details on using hashes here.

File details

Details for the file essentials_openapi-1.0.9-py3-none-any.whl.

File metadata

File hashes

Hashes for essentials_openapi-1.0.9-py3-none-any.whl
Algorithm Hash digest
SHA256 1431e98ef0a442f1919fd9833385bf44d832c355fd05919dc06d43d4da0f8ef4
MD5 5d8f77826e1e187fb53bbb47d68c19ca
BLAKE2b-256 dfba71f33232e10c34240ecc30582129b57e807c0e5b6aa18ff1b3c50481fc7f

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page