Voluptuous OpenAPI Converter

Common errors

• ModuleNotFoundError: No module named 'voluptuous_openapi'

  cause The 'voluptuous-openapi' library has not been installed in the current Python environment.
  fix Run `pip install voluptuous-openapi` to install the package.

• voluptuous.error.Invalid: extra keys not allowed @ data['unexpected_key']

  cause The input data being validated by a Voluptuous schema contains keys that were not explicitly defined in the schema, and extra keys are not permitted by default.
  fix Modify your `voluptuous.Schema` definition to explicitly handle extra keys. Use `vol.Schema(..., extra=vol.ALLOW_EXTRA)` to permit them, or `vol.Schema(..., extra=vol.REMOVE_EXTRA)` to silently ignore them.

• Generated OpenAPI schema does not include a specific OpenAPI feature (e.g., `oneOf`, `anyOf`, advanced validation rules) or is not fully compliant with OpenAPI 3.1.

  cause `voluptuous-openapi` might not yet support all advanced features of the latest OpenAPI specifications, or the Voluptuous schema used might not be expressive enough to translate into the desired OpenAPI constructs.
  fix Consult the `voluptuous-openapi` GitHub repository and documentation for supported OpenAPI versions and features. For complex or custom validators, explore implementing a custom serializer as described in the library's README to extend its conversion capabilities.

Warnings

• breaking OpenAPI Specification 3.1 introduced breaking changes compared to 3.0, notably replacing `nullable` with type arrays and aligning with JSON Schema Draft 2020-12. If `voluptuous-openapi` targets 3.0, users aiming for 3.1 might encounter compatibility issues or missing features.
  Fix: Verify the OpenAPI Specification version generated by `voluptuous-openapi` and ensure it matches the target environment. Manual adjustments to the generated schema may be required for full 3.1 compliance if not natively supported.
• gotcha The upstream `voluptuous` library, on which `voluptuous-openapi` depends, is in 'contributions only' mode, indicating that the original author is not actively developing new features or fixing bugs directly. This could impact the long-term evolution or responsiveness to new features/fixes for `voluptuous-openapi` related to underlying `voluptuous` capabilities.
  Fix: Be aware that feature requests or complex bug fixes requiring upstream changes in `voluptuous` might have limited support. Consider contributing fixes if critical issues arise.
• gotcha OpenAPI 3.0 had a known limitation where descriptions could not be directly provided alongside `$ref` references, making it difficult to fully document reusable components. If `voluptuous-openapi` generates 3.0-compliant schemas, this documentation gap might persist.
  Fix: For OpenAPI 3.0 targets, consider workarounds like the 'allOf hack' mentioned in community discussions, or upgrade to OpenAPI 3.1 if possible, which addresses this issue.

Install

• pip install voluptuous-openapi==0.3.0 Install latest version

Imports

• convert

  from voluptuous_openapi import convert

  The primary function to convert Voluptuous schemas.
• vol

  import voluptuous as vol

  Common alias for the underlying voluptuous library for schema definition.

Quickstart

This quickstart demonstrates how to define a basic Voluptuous schema with required, optional, and type-specific validators, and then convert it into a dictionary representing an OpenAPI Schema object using `voluptuous-openapi.convert`.

import voluptuous as vol
from voluptuous_openapi import convert

# Define a simple Voluptuous schema
schema = vol.Schema({
    vol.Required('name'): vol.All(str, vol.Length(min=5)),
    vol.Optional('age'): vol.All(int, vol.Range(min=0)),
    'email': vol.Email,
})

# Convert the Voluptuous schema to an OpenAPI Schema object
openapi_schema = convert(schema)

# Print the resulting OpenAPI schema (dictionary representation)
import json
print(json.dumps(openapi_schema, indent=2))