OpenAPI Codec for Core API

1.3.2 · abandoned · verified Thu Apr 16

OpenAPI-codec is a Python library that functions as a codec for the OpenAPI schema format (also known as Swagger) within the Core API framework. It enables Python clients to interact with services exposing OpenAPI schemas and automatically integrates with the Core API command-line client upon installation. The project's last update on GitHub was 7 years ago, and its latest release on PyPI was in July 2017, indicating that it is no longer actively maintained.

Common errors

```
ModuleNotFoundError: No module named 'openapi_codec'
```
cause The `openapi-codec` library has not been installed in the current Python environment.

fix Run `pip install openapi-codec` to install the package.
```
coreapi.exceptions.ParseError: Could not determine format. Expected one of...
```
cause Core API failed to automatically detect the OpenAPI format, often because the server returned a generic `Content-Type` header (e.g., `application/json`) for an OpenAPI schema.

fix When fetching the schema, explicitly specify the format: `client.get(url, format='openapi')` or `coreapi get <url> --format openapi`.
```
TypeError: __init__() got an unexpected keyword argument 'decoders'
```
cause This error likely indicates an incompatibility or an outdated version of `coreapi` when trying to instantiate the `Client` with `decoders`. Alternatively, if `OpenAPICodec` itself is instantiated with unexpected arguments, but the primary example uses it without args.

fix Ensure `coreapi` is installed and up-to-date (though note the overall maintenance status). Review `coreapi` documentation for client instantiation if this issue persists. The correct pattern is `client = Client(decoders=decoders)`.

Warnings

breaking The library is abandoned; the last release was in July 2017, and the GitHub repository shows no activity for the past 7 years. This means it's unlikely to support newer Python versions, recent OpenAPI Specification (OAS) versions (e.g., 3.1, 3.2), or receive security patches.
Fix: Consider migrating to actively maintained alternatives or custom parsing solutions if full OpenAPI v3+ support is required.
gotcha If the API server exposes the OpenAPI schema using a generic `application/json` content type instead of `application/openapi+json`, the `OpenAPICodec` might not be automatically selected by Core API.
Fix: Explicitly include `format='openapi'` in your `client.get()` or `coreapi` CLI command to force the use of `OpenAPICodec`.
deprecated The Core API framework itself, which `openapi-codec` depends on, also appears to be unmaintained. This means the entire ecosystem might be outdated and incompatible with modern Python practices or security standards.
Fix: Evaluate the current maintenance status of `coreapi` and consider its implications for your project's long-term stability and security.

Install

pip install openapi-codec Install with pip

Imports

OpenAPICodec
wrong:
```
from openapi_codec.codec import OpenAPICodec
```
correct:
```
from openapi_codec import OpenAPICodec
```
The primary codec class is directly available under the top-level package.

Quickstart

This quickstart demonstrates how to initialize a Core API client with the `OpenAPICodec` to interact with services exposing OpenAPI schemas. It highlights the need to explicitly specify `format='openapi'` if the server does not correctly use the `application/openapi+json` content type.

from openapi_codec import OpenAPICodec
from coreapi.codecs import JSONCodec
from coreapi import Client

# Configure decoders for the Core API client
decoders = [OpenAPICodec(), JSONCodec()]
client = Client(decoders=decoders)

# Example of fetching a schema that might require explicit format if content-type is generic
# Use a public OpenAPI schema URL for demonstration, e.g., petstore.swagger.io
# Note: This URL might return 'application/json' so format='openapi' is crucial.
# Ensure COREAPI_FORMAT_OPENAPI is set in your environment or passed directly.
# For a live example, you might need a service that truly serves 'application/openapi+json'.
# This code assumes a valid OpenAPI JSON is returned at the URL.

try:
    # Simulate a fetch, if direct URL doesn't work, consider a local file or mock.
    # For a real API, replace with the actual URL and handle potential authentication.
    document = client.get('http://petstore.swagger.io/v2/swagger.json', format='openapi')
    print('Successfully decoded OpenAPI document:')
    print(document.title)
    print(f'Number of endpoints: {len(document.data)}')
except Exception as e:
    print(f'Error decoding document: {e}')
    print('Ensure the URL serves a valid OpenAPI schema and Core API/openapi-codec are installed.')

view raw JSON →