Skip to main content
Help the Python Software Foundation raise $60,000 USD by December 31st!  Building the PSF Q4 Fundraiser

No project description provided

Project description

https://img.shields.io/pypi/v/openapi-core.svg https://travis-ci.org/p1c2u/openapi-core.svg?branch=master https://img.shields.io/codecov/c/github/p1c2u/openapi-core/master.svg?style=flat https://img.shields.io/pypi/pyversions/openapi-core.svg https://img.shields.io/pypi/format/openapi-core.svg https://img.shields.io/pypi/status/openapi-core.svg

About

Openapi-core is a Python library that adds client-side and server-side support for the OpenAPI Specification v3.0.0.

Installation

Recommended way (via pip):

$ pip install openapi-core

Alternatively you can download the code and install from the repository:

$ pip install -e git+https://github.com/p1c2u/openapi-core.git#egg=openapi_core

Usage

Firstly create your specification:

from openapi_core import create_spec

spec = create_spec(spec_dict)

Request

Now you can use it to validate requests

from openapi_core.validation.request.validators import RequestValidator

validator = RequestValidator(spec)
result = validator.validate(request)

# raise errors if request invalid
result.raise_for_errors()

# get list of errors
errors = result.errors

and unmarshal request data from validation result

# get parameters object with path, query, cookies and headers parameters
validated_params = result.parameters
# or specific parameters
validated_path_params = result.parameters.path

# get body
validated_body = result.body

# get security data
validated_security = result.security

Request object should be instance of OpenAPIRequest class (See Integrations).

Response

You can also validate responses

from openapi_core.validation.response.validators import ResponseValidator

validator = ResponseValidator(spec)
result = validator.validate(request, response)

# raise errors if response invalid
result.raise_for_errors()

# get list of errors
errors = result.errors

and unmarshal response data from validation result

# get headers
validated_headers = result.headers

# get data
validated_data = result.data

Response object should be instance of OpenAPIResponse class (See Integrations).

Security

openapi-core supports security for authentication and authorization process. Security data for security schemas are accessible from security attribute of RequestValidationResult object.

For given security specification:

security:
  - BasicAuth: []
  - ApiKeyAuth: []
components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

you can access your security data the following:

result = validator.validate(request)

# get basic auth decoded credentials
result.security['BasicAuth']

# get api key
result.security['ApiKeyAuth']

Supported security types:

  • http – for Basic and Bearer HTTP authentications schemes
  • apiKey – for API keys and cookie authentication

Customizations

Deserializers

Pass custom defined media type deserializers dictionary with supported mimetypes as a key to RequestValidator or ResponseValidator constructor:

def protobuf_deserializer(message):
    feature = route_guide_pb2.Feature()
    feature.ParseFromString(message)
    return feature

custom_media_type_deserializers = {
    'application/protobuf': protobuf_deserializer,
}

validator = ResponseValidator(
    spec, custom_media_type_deserializers=custom_media_type_deserializers)

result = validator.validate(request, response)

Formats

OpenAPI defines a format keyword that hints at how a value should be interpreted, e.g. a string with the type date should conform to the RFC 3339 date format.

Openapi-core comes with a set of built-in formatters, but it’s also possible to add support for custom formatters for RequestValidator and ResponseValidator.

Here’s how you could add support for a usdate format that handles dates of the form MM/DD/YYYY:

 from datetime import datetime
 import re

 class USDateFormatter:
     def validate(self, value) -> bool:
         return bool(re.match(r"^\d{1,2}/\d{1,2}/\d{4}$", value))

     def unmarshal(self, value):
         return datetime.strptime(value, "%m/%d/%y").date


custom_formatters = {
    'usdate': USDateFormatter(),
}

validator = ResponseValidator(spec, custom_formatters=custom_formatters)

result = validator.validate(request, response)

Integrations

Django

For Django 2.2 you can use DjangoOpenAPIRequest a Django request factory:

from openapi_core.validation.request.validators import RequestValidator
from openapi_core.contrib.django import DjangoOpenAPIRequest

openapi_request = DjangoOpenAPIRequest(django_request)
validator = RequestValidator(spec)
result = validator.validate(openapi_request)

You can use DjangoOpenAPIResponse as a Django response factory:

from openapi_core.validation.response.validators import ResponseValidator
from openapi_core.contrib.django import DjangoOpenAPIResponse

openapi_response = DjangoOpenAPIResponse(django_response)
validator = ResponseValidator(spec)
result = validator.validate(openapi_request, openapi_response)

Falcon

This section describes integration with Falcon web framework.

Middleware

Falcon API can be integrated by FalconOpenAPIMiddleware middleware.

from openapi_core.contrib.falcon.middlewares import FalconOpenAPIMiddleware

openapi_middleware = FalconOpenAPIMiddleware.from_spec(spec)
api = falcon.API(middleware=[openapi_middleware])

Low level

For Falcon you can use FalconOpenAPIRequest a Falcon request factory:

from openapi_core.validation.request.validators import RequestValidator
from openapi_core.contrib.falcon import FalconOpenAPIRequestFactory

openapi_request = FalconOpenAPIRequestFactory.create(falcon_request)
validator = RequestValidator(spec)
result = validator.validate(openapi_request)

You can use FalconOpenAPIResponse as a Falcon response factory:

from openapi_core.validation.response.validators import ResponseValidator
from openapi_core.contrib.falcon import FalconOpenAPIResponseFactory

openapi_response = FalconOpenAPIResponseFactory.create(falcon_response)
validator = ResponseValidator(spec)
result = validator.validate(openapi_request, openapi_response)

Flask

Decorator

Flask views can be integrated by FlaskOpenAPIViewDecorator decorator.

from openapi_core.contrib.flask.decorators import FlaskOpenAPIViewDecorator

openapi = FlaskOpenAPIViewDecorator.from_spec(spec)

@app.route('/home')
@openapi
def home():
    pass

If you want to decorate class based view you can use the decorators attribute:

class MyView(View):
    decorators = [openapi]

View

As an alternative to the decorator-based integration, Flask method based views can be integrated by inheritance from FlaskOpenAPIView class.

from openapi_core.contrib.flask.views import FlaskOpenAPIView

class MyView(FlaskOpenAPIView):
    pass

app.add_url_rule('/home', view_func=MyView.as_view('home', spec))

Request parameters

In Flask, all unmarshalled request data are provided as Flask request object’s openapi.parameters attribute

from flask.globals import request

@app.route('/browse/<id>/')
@openapi
def home():
    browse_id = request.openapi.parameters.path['id']
    page = request.openapi.parameters.query.get('page', 1)

Low level

You can use FlaskOpenAPIRequest a Flask/Werkzeug request factory:

from openapi_core.validation.request.validators import RequestValidator
from openapi_core.contrib.flask import FlaskOpenAPIRequest

openapi_request = FlaskOpenAPIRequest(flask_request)
validator = RequestValidator(spec)
result = validator.validate(openapi_request)

You can use FlaskOpenAPIResponse as a Flask/Werkzeug response factory:

from openapi_core.validation.response.validators import ResponseValidator
from openapi_core.contrib.flask import FlaskOpenAPIResponse

openapi_response = FlaskOpenAPIResponse(flask_response)
validator = ResponseValidator(spec)
result = validator.validate(openapi_request, openapi_response)

Pyramid

See pyramid_openapi3 project.

Requests

This section describes integration with Requests library.

Low level

For Requests you can use RequestsOpenAPIRequest a Requests request factory:

from openapi_core.validation.request.validators import RequestValidator
from openapi_core.contrib.requests import RequestsOpenAPIRequest

openapi_request = RequestsOpenAPIRequest(requests_request)
validator = RequestValidator(spec)
result = validator.validate(openapi_request)

You can use RequestsOpenAPIResponse as a Requests response factory:

from openapi_core.validation.response.validators import ResponseValidator
from openapi_core.contrib.requests import RequestsOpenAPIResponse

openapi_response = RequestsOpenAPIResponse(requests_response)
validator = ResponseValidator(spec)
result = validator.validate(openapi_request, openapi_response)

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for openapi-core, version 0.13.4
Filename, size File type Python version Upload date Hashes
Filename, size openapi_core-0.13.4-py2-none-any.whl (80.3 kB) File type Wheel Python version py2 Upload date Hashes View
Filename, size openapi_core-0.13.4-py3-none-any.whl (80.3 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size openapi-core-0.13.4.tar.gz (35.8 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page