Testing that OpenAPI Spec is valid with OpenAPI Spec Validator and Pytest

API specifications like the OpenAPI specification are important tools to document HTTP APIs in a strict and computer-readable way. When I joined Baserow, we also had a generated OpenAPI specification for the Baserow API. However, it wasn't valid. Invalid spec makes it impossible for users to easily import it in API tools like Postman, and prevent developers from using client code generators to use such API.

So whether we write the spec by hand or use a library to generate it, it is always a good idea to have an automated test running as part of our test suite to prevent such scenario. This is where OpenAPI Spec Validator library for Python comes in! I used it originally to write such test at work, but I now include it in any project that involves an API for third-party consumption.

The library will work with all the major OpenAPI versions (OpenAPI 2.0 (aka Swagger), OpenAPI 3.0 and OpenAPI 3.1). In my example I am using pytest and Django REST Framework, but it is easily adaptable to another framework. All we need to do is provide the validator the JSON that should be validated:

import pytest
from openapi_spec_validator import openapi_v3_spec_validator
from rest_framework.reverse import reverse


@pytest.mark.django_db
def test_openapi_spec(client):
    response = client.get(reverse("schema") + "?format=json")

    # If no exception is raised the spec is valid
    openapi_v3_spec_validator.validate(response.json())

In the above example, I work with a generated OpenAPI spec that would be available on a particular URL, e.g. through drf-spectacular. It is also possible to just read a spec file or obtain it in another way. Note that the client test fixture refers to the Django test client and pytest.mark.django_db to a pytest marker that enables testing a Django application using a database, both are injected thanks to pytest-django package.

Also note that the correct validator needs to be imported based on the provided OpenAPI spec version. In here the openapi_v3_spec_validator validates version 3.0.

Last updated on 18.12.2022.