{"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":"python","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":[{"wrong":"from openapidocs import OpenAPI","symbol":"OpenAPI","correct":"from openapidocs import OpenAPI"}],"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,"search_vec":"'1.4.0':11 'activ':48 'ad':60 'address':56 'also':31 'api':70 'api-document':69 'bug':57 'cadenc':54 'capabl':25 'current':9 'design':12 'document':16,39,71 'essenti':1,3 'exist':41 'file':44 'fix':58 'format':22 'generat':14,35 'json':27,73 'librari':8 'maintain':49 'newer':63 'often':55 'openapi':2,4,15,42,64,67 'output':24 'project':46 'provid':32 'python':7 'regular':52 'releas':53 'specif':43,65,72 'support':61 'swagger':68 'type':37 'util':33 'v2':21 'v3':19 'version':10,66 'yaml':29,74","created_at":"2026-04-16T17:00:38.977997+00:00","updated_at":"2026-04-16T17:00:38.977997+00:00","problems":{"verify_error":"Traceback (most recent call last):\n  File \"<string>\", line 1, in <module>\nImportError: cannot import name 'OpenAPI' from 'openapidocs' (/tmp/tmpp30_66ei/venv/lib/python3.12/site-packages/openapidocs/__init__.py)"},"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.4.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/Neoteroi/essentials-openapi","docs":null,"changelog":null,"pypi":"https://pypi.org/project/essentials-openapi/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework","serialization","http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"import_fail","verified_at":"2026-07-03","last_verified":"2026-07-03","next_check":"2026-07-10","install_tag":null}}