• Python 3.6 or higher

  • Setuptools 30.3.0 or higher

  • Only the PostgreSQL database is supported

Install from PyPI

Install from PyPI with pip:

pip install vng-api-common

You will also need the NPM package swagger2openapi:

npm install swagger2openapi

Configure the Django settings

  1. Add vng_api_common to INSTALLED_APPS, with the rest of the dependencies:

        'django.contrib.sites',  # required if using the notifications
        'vng_api_common',  # before drf_yasg to override the management command
        'vng_api_common.notifications',  # optional
        'vng_api_common.audittrails',  # optional
        'solo',  # required for authorizations and notifications
  2. Add the required middleware:

     1 MIDDLEWARE = [
     2     'django.middleware.security.SecurityMiddleware',
     3     'django.contrib.sessions.middleware.SessionMiddleware',
     4     'django.middleware.common.CommonMiddleware',
     5     'django.middleware.csrf.CsrfViewMiddleware',
     6     'django.contrib.auth.middleware.AuthenticationMiddleware',
     7     'vng_api_common.middleware.AuthMiddleware',
     8     'django.contrib.messages.middleware.MessageMiddleware',
     9     'django.middleware.clickjacking.XFrameOptionsMiddleware',
    10     'vng_api_common.middleware.APIVersionHeaderMiddleware',
    11 ]
  3. Add the default API settings:

    from vng_api_common.conf.api import *  # noqa

    Imports are white-listed in the shipped settings module, so it’s actually safe to do import * ;)

  4. See vng_api_common/conf/api.py for a list of available settings.

Configure the Node tooling

In the package.json of your project, add the scripts entry for convert:

    "scripts": {
      "convert": "swagger2openapi src/swagger2.0.json -o src/openapi.yaml"


API Spec generation

To generate the API spec, run:


This will output:

  • src/swagger2.0.json: the OAS 2 specification

  • src/openapi.yaml: the OAS 3 specification

  • src/resources.md: a list of the exposed resources

See the reference implementations of ZRC, DRC, BRC en ZTC to see it in action.

Run-time functionality

See the rest of the documentation for the available modules and packages.