{"id":8140,"library":"essentials-openapi","title":"Essentials OpenAPI","description":"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.","status":"active","version":"1.4.0","language":"en","source_language":"en","source_url":"https://github.com/Neoteroi/essentials-openapi","tags":["openapi","swagger","api-documentation","specification","json","yaml"],"install":[{"cmd":"pip install essentials-openapi","lang":"bash","label":"Base installation"},{"cmd":"pip install essentials-openapi[full]","lang":"bash","label":"With dependencies for artifact generation (e.g., MkDocs, PlantUML)"}],"dependencies":[{"reason":"Required Python version","package":"python","min_version":"3.10"},{"reason":"Required for rendering and escaping, became mandatory from v1.0.9.","package":"MarkupSafe","min_version":"3.0.0"},{"reason":"Required for YAML parsing and serialization.","package":"PyYAML","min_version":"6"},{"reason":"Enables schema generation from Pydantic models (Pydantic v2+ support from v1.0.9), included with '[full]' extra.","package":"pydantic","optional":true,"min_version":"2"}],"imports":[{"note":"Primary class for building OpenAPI v3 specifications.","symbol":"OpenAPI","correct":"from essentials_openapi.v3 import OpenAPI"},{"note":"Example of importing a model object for OpenAPI spec details.","symbol":"Contact","correct":"from essentials_openapi.v3.models import Contact"}],"quickstart":{"code":"from essentials_openapi.v3 import OpenAPI, Info, PathItem, Operation, Response, MediaType, Schema, Contact\nfrom essentials_openapi.v3.models import Reference\n\n# Define contact information\ncontact_info = Contact(name='API Support', email='support@example.com')\n\n# Define basic API information\ninfo = Info(\n    title='My Sample API',\n    version='1.0.0',\n    description='A simple API to demonstrate essentials-openapi.',\n    contact=contact_info\n)\n\n# Define a simple response schema\nsuccess_schema = Schema(type='object', properties={'message': Schema(type='string')})\n\n# Define a successful response\nsuccess_response = Response(\n    description='Successful operation',\n    content={'application/json': MediaType(schema=Reference(ref='#/components/schemas/SuccessResponse'))}\n)\n\n# Define an operation for a GET endpoint\nget_operation = Operation(\n    summary='Get a greeting',\n    responses={'200': success_response}\n)\n\n# Define a path item\npath_item = PathItem(get=get_operation)\n\n# Create the OpenAPI object\nopenapi = OpenAPI(\n    info=info,\n    paths={'/greet': path_item},\n    components={'schemas': {'SuccessResponse': success_schema}}\n)\n\n# Generate the OpenAPI JSON output\nopenapi_json = openapi.to_json(indent=2)\nprint(openapi_json)\n\n# To save to a file (requires PyYAML for YAML, or built-in json for JSON)\n# with open('openapi.json', 'w') as f:\n#     f.write(openapi_json)\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.4.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.","message":"Support for Python 3.8 was officially dropped with the release of version 1.1.0.","severity":"deprecated","affected_versions":">=1.1.0"},{"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`.","message":"`MarkupSafe` transitioned from a potentially optional/implicit dependency to a mandatory one.","severity":"gotcha","affected_versions":">=1.0.9"},{"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.","message":"The library updated its internal representation to align with OpenAPI Specification v3.1.","severity":"gotcha","affected_versions":">=1.2.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Upgrade MarkupSafe to a compatible version: `pip install --upgrade MarkupSafe`. Ensure `MarkupSafe>=1.1.1` is installed.","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.","error":"ImportError: cannot import name 'Feature' from 'setuptools'"},{"fix":"Install the `PyYAML` dependency: `pip install PyYAML`. Additionally, carefully check your YAML input file for syntax errors.","cause":"This typically indicates that the `PyYAML` library is either not installed or the input YAML file is malformed and cannot be parsed correctly.","error":"YAML loading error: while parsing a block collection"},{"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.","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.","error":"essentials_openapi.exceptions.OpenAPIError: Generation of artifacts from Swagger v2 specification files is not supported."}]}