Quickstart

Requirements

  • Python 3.9 or above

  • Django 4.2 or newer

Installation

  1. Add open-api-framework to your requirements file

  2. Remove dependencies from your requirements file that occur in pyproject.toml

  3. Recompile the dependencies

Usage

If you want to reuse the generic base settings, you can do the following:

Add the following imports to the top of the project’s base.py file:

from open_api_framework.conf.base import *  # noqa
from open_api_framework.conf.utils import config

After that, compare the settings from open_api_framework.conf.base to the settings defined in the project’s base.py and remove settings from the latter to make use of the generic settings (if this is desired).

Warning

All settings defined in open_api_framework.conf.base will be loaded when importing from that file, even if only specific settings are imported.

Documenting environment variables

This library provides utilities and a management command to generate .rst style documentation for environment variables that are in your project. The open_api_framework.conf.utils.config() can be used for this as follows to specify environment variable documentation. By default, all environment variables are added to the documentation (unless add_to_docs=False is passed to config).

from open_api_framework.conf.base import *  # noqa
from open_api_framework.conf.utils import config

config(
    "DB_NAME",
    PROJECT_DIRNAME,
    group="Database",
    help_text="name of the PostgreSQL database.",
)

The generic base settings are documented in the same way, so these will be automatically picked up when generating the documentation. In order to generate the documentation, the run the following command:

python src/manage.py generate_envvar_docs --file docs/installation/config.rst

If no --file is supplied, it will write to docs/env_config.rst. Additionally, if some groups do not apply for your project, they can be excluded from the docs like this:

python src/manage.py generate_envvar_docs --exclude-group Celery --exclude-group Cross-Origin-Resource-Sharing

In order to add extra information for your project, add a template in templates/open_api_framework/env_config.rst and customize it:

{% extends "open_api_framework/env_config.rst" %}

{% block intro %}
Intro
-----

<some introductory information>

{% endblock %}

{% block extra %}

Custom section
--------------

<some extra information>

{% endblock %}

Note

Currently only environment variables that are part of settings or modules that are loaded when running management commands are included in the documentation