Quickstart
Installation
Pre-requisites
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
Add
vng_api_common
toINSTALLED_APPS
, with the rest of the dependencies:INSTALLED_APPS = [ ..., 'django.contrib.sites', # required if using the notifications 'django_filters', 'vng_api_common', # before drf_yasg to override the management command 'vng_api_common.authorizations', 'vng_api_common.notifications', # optional 'vng_api_common.audittrails', # optional 'drf_yasg', 'rest_framework', 'solo', # required for authorizations and notifications ... ]
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 ]
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 *
;)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"
}
}
Usage
API Spec generation
To generate the API spec, run:
generate_schema
This will output:
src/swagger2.0.json
: the OAS 2 specificationsrc/openapi.yaml
: the OAS 3 specificationsrc/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.