Essentials OpenAPI

1.4.0 · active · verified Thu Apr 16

Essentials OpenAPI is a Python library (current version 1.4.0) designed for generating OpenAPI Documentation in both v3 and v2 formats, with output capabilities in JSON and YAML. It also provides utilities for generating other types of documents from existing OpenAPI Specification files. The project is actively maintained with a regular release cadence, often addressing bug fixes and adding support for newer OpenAPI specification versions.

Common errors

```
ImportError: cannot import name 'Feature' from 'setuptools'
```
cause An older version of MarkupSafe (prior to 1.1.1) is incompatible with newer versions of setuptools, leading to an import error during installation or usage.

fix Upgrade MarkupSafe to a compatible version: `pip install --upgrade MarkupSafe`. Ensure `MarkupSafe>=1.1.1` is installed.
```
YAML loading error: while parsing a block collection
```
cause This typically indicates that the `PyYAML` library is either not installed or the input YAML file is malformed and cannot be parsed correctly.

fix Install the `PyYAML` dependency: `pip install PyYAML`. Additionally, carefully check your YAML input file for syntax errors.
```
essentials_openapi.exceptions.OpenAPIError: Generation of artifacts from Swagger v2 specification files is not supported.
```
cause You are attempting to use the library's artifact generation features (e.g., `oad gen-docs`) with an OpenAPI v2 (Swagger) specification file on version 1.4.0 or newer, which only supports OpenAPI v3.x for this functionality.

fix Convert your OpenAPI v2 (Swagger) specification to OpenAPI v3.x format before using it with `essentials-openapi`. You can use various online tools or libraries for this conversion.

Warnings

breaking Attempting to generate output artifacts from OpenAPI v2 (Swagger) specification files will now raise an error. The library's artifact generation features (e.g., via the 'oad gen-docs' CLI) exclusively support OpenAPI v3.x.
Fix: Convert your Swagger (OpenAPI v2) specification to OpenAPI v3.x format before processing with `essentials-openapi`. Several online converters and tools are available for this purpose.
deprecated Support for Python 3.8 was officially dropped with the release of version 1.1.0.
Fix: Users running Python 3.8 or older must upgrade their Python environment to version 3.9 or newer to use `essentials-openapi` v1.1.0 and subsequent releases.
gotcha `MarkupSafe` transitioned from a potentially optional/implicit dependency to a mandatory one.
Fix: Ensure `MarkupSafe` is explicitly installed and up-to-date (`pip install --upgrade MarkupSafe`). Older versions of `MarkupSafe` (prior to 1.1.1) can cause `ImportError: cannot import name 'Feature' from 'setuptools'` with newer `setuptools`.
gotcha The library updated its internal representation to align with OpenAPI Specification v3.1.
Fix: While OAS 3.1 is largely backward compatible with 3.0.x, users relying on very specific 3.0.x behaviors or tooling might encounter subtle differences. Review generated specs for compatibility with downstream tools if issues arise.

Install

pip install essentials-openapi Base installation
pip install essentials-openapi[full] With dependencies for artifact generation (e.g., MkDocs, PlantUML)

Imports

OpenAPI
```
from essentials_openapi.v3 import OpenAPI
```
Primary class for building OpenAPI v3 specifications.
Contact
```
from essentials_openapi.v3.models import Contact
```
Example of importing a model object for OpenAPI spec details.

Quickstart

This quickstart demonstrates how to programmatically construct a minimal OpenAPI v3 specification using `essentials-openapi`. It defines API info, a basic path with a GET operation, and a response schema, then outputs the specification as JSON. This approach directly uses the library's Python classes to build the OpenAPI document structure.

from essentials_openapi.v3 import OpenAPI, Info, PathItem, Operation, Response, MediaType, Schema, Contact
from essentials_openapi.v3.models import Reference

# Define contact information
contact_info = Contact(name='API Support', email='support@example.com')

# Define basic API information
info = Info(
    title='My Sample API',
    version='1.0.0',
    description='A simple API to demonstrate essentials-openapi.',
    contact=contact_info
)

# Define a simple response schema
success_schema = Schema(type='object', properties={'message': Schema(type='string')})

# Define a successful response
success_response = Response(
    description='Successful operation',
    content={'application/json': MediaType(schema=Reference(ref='#/components/schemas/SuccessResponse'))}
)

# Define an operation for a GET endpoint
get_operation = Operation(
    summary='Get a greeting',
    responses={'200': success_response}
)

# Define a path item
path_item = PathItem(get=get_operation)

# Create the OpenAPI object
openapi = OpenAPI(
    info=info,
    paths={'/greet': path_item},
    components={'schemas': {'SuccessResponse': success_schema}}
)

# Generate the OpenAPI JSON output
openapi_json = openapi.to_json(indent=2)
print(openapi_json)

# To save to a file (requires PyYAML for YAML, or built-in json for JSON)
# with open('openapi.json', 'w') as f:
#     f.write(openapi_json)

view raw JSON →