django-swagger-tester 2.0.0

Django Swagger Tester

Documentation: https://django-swagger-tester.readthedocs.io

Repository: https://github.com/sondrelg/django-swagger-tester

This package is a simple test utility for your Django Swagger documentation.

Its aim is to make it easy for developers to catch and correct documentation errors in their Swagger docs by comparing documented responses to actual API responses, or validating documented request bodies using actual input serializers.

Installation

Install using pip:

pip install django-swagger-tester

Configuration

INSTALLED_APPS = [
    ...
    'django_swagger_tester',
]

from django_swagger_tester.loaders import StaticSchemaLoader
from django_swagger_tester.case_testers import is_camel_case

SWAGGER_TESTER = {
    'SCHEMA_LOADER': StaticSchemaLoader,
    'PATH': './static/openapi-schema.yml',
    'CASE_TESTER': is_camel_case,
    'CASE_PASSLIST': [],
    'CAMEL_CASE_PARSER': False,
}

from django_swagger_tester.loaders import DrfYasgSchemaLoader

SWAGGER_TESTER = {
    'SCHEMA_LOADER': DrfYasgSchemaLoader,
}

SWAGGER_TESTER = {
    'PATH': BASE_DIR / '/openapi-schema.yml',
}

from django_swagger_tester.case_testers import is_camel_case

SWAGGER_TESTER = {
    'CASE_TESTER': is_camel_case,
}

from django_swagger_tester.case_testers import is_camel_case

SWAGGER_TESTER = {
    'CASE_PASSLIST': ['IP', 'DHCP'],
}

SWAGGER_TESTER = {
    'CAMEL_CASE_PARSER': True,
}

Response Validation

To make sure your API response matches your documented response, the validate_response function compares the two at each level of depth.

A pytest implementation might look like this:

from django_swagger_tester.testing import validate_response

def test_200_response_documentation(client):
    route = 'api/v1/test/1'
    response = client.get(route)
    assert response.status_code == 200
    assert response.json() == expected_response

    # test swagger documentation
    validate_response(response=response, method='GET', route=route)

A Django-test implementation might look like this:

from django_swagger_tester.testing import validate_response

class MyApiTest(APITestCase):

    path = '/api/v1/test/'

    def setUp(self) -> None:
        user, _ = User.objects.update_or_create(username='test_user')
        self.client.force_authenticate(user=user)

    def test_get_200(self) -> None:
        response = self.client.get(self.path, headers={'Content-Type': 'application/json'})
        expected_response = [...]

        self.assertEqual(response.status_code, 200)
        self.assertEqual(response.json(), expected_response)

        # test swagger documentation
        validate_response(response=response, method='GET', route=self.path)

It is also possible to test more than a single response at the time:

def test_post_endpoint_responses(client):
    # 201 - Resource created
    response = client.post(...)
    validate_response(response=response, method='POST', route='api/v1/test/')

    # 400 - Bad data
    response = client.post(...)
    validate_response(response=response, method='POST', route='api/v1/test/')

def test_get_endpoint_responses(client):
    # 200 - Fetch resource
    response = client.get(...)
    validate_response(response=response, method='GET', route='api/v1/test/<id>')

    # 404 - Bad ID
    response = client.get(...)
    validate_response(response=response, method='GET', route='api/v1/test/<bad id>')

django_swagger_tester.exceptions.SwaggerDocumentationError: Item is misspecified:

Summary
-------------------------------------------------------------------------------------------

Error:      The following properties seem to be missing from your response body: length, width.

Expected:   {'name': 'Saab', 'color': 'Yellow', 'height': 'Medium height', 'width': 'Very wide', 'length': '2 meters'}
Received:   {'name': 'Saab', 'color': 'Yellow', 'height': 'Medium height'}

Hint:       Remove the key(s) from you Swagger docs, or include it in your API response.
Sequence:   init.list

-------------------------------------------------------------------------------------------

* If you need more details: set `verbose=True`

Input Validation

To make sure your request body documentation is accurate, and will stay accurate, you can use endpoint serializers to validate your schema directly.

validate_input_serializer constructs an example representation of the documented request body, and passes it to the serializer it is given. This means it’s only useful if you use serializers for validating your incoming request data.

A Django test implementation of input validation for a whole project could be structured like this:

from django.test import SimpleTestCase
from django_swagger_tester.testing import validate_input_serializer

from api.serializers.validation.request_bodies import ...


class TestSwaggerInput(SimpleTestCase):
    endpoints = [
        {
            'api/v1/orders/': [
                ('POST', ValidatePostOrderBody),
                ('PUT', ValidatePutOrderBody),
                ('DELETE', ValidateDeleteOrderBody)
            ]
        },
        {
            'api/v1/orders/<id>/entries/': [
                ('POST', ValidatePostEntryBody),
                ('PUT', ValidatePutEntryBody),
                ('DELETE', ValidateEntryDeleteBody)
            ]
        },
    ]

    def test_swagger_input(self) -> None:
        """
        Verifies that the documented request bodies are valid.
        """
        for endpoint in self.endpoints:
            for route, values in endpoint.items():
                for method, serializer in values:
                    validate_input_serializer(serializer=serializer, method=method, route=route)