Getting started

Requirements

drf-connect-docs has the following requirements:

• Python 3.10+

• Django 2.2.*

• Django Rest Framework 3.11.*

• uritemplate 3.0.1

• inflect 4.1.0

• pyyaml 5.3.1

• requests 2.23.*

• django-rql 3.2+

• django-fsm 2.6.0+

Install

$ pip install --extra-index-url "https://repo.int.zone/artifactory/api/pypi/pypi/simple" drf-connect-docs

Configure

Configure Django

You must add the cnctdocs application to the django INSTALLED_APPS setting.

INSTALLED_APPS = [
    ...
    'rest_framework',
    'cnctdocs',
    ...
]

Configure Django Rest Framework

To use drf-connect-docs we have to tell DRF which AutoSchema class to use.

To do so, we need to add the following to the REST_FRAMEWORK setting:

REST_FRAMEWORK = {
    ...
    'DEFAULT_SCHEMA_CLASS': 'cnctdocs.schemas.ConnectAutoSchema',
    ...
}

Since we use as base path /public/v1 we need to properly handle API versioning using DRF provided mechanism.

To configure it:

REST_FRAMEWORK = {
    ...
    'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.URLPathVersioning',
    'DEFAULT_VERSION': 'v1',
    'VERSION_PARAM': 'api_version',
    ...
}

Configure drf-connect-docs

drf-connect-docs has the following default settings:

{
    'SCHEMA_INFO': {
        'title': 'CloudBlue Connect API',
        'version': '0.0.1',
        'description': DEFAULT_DESCRIPTION,
    },
    'SCHEMA': {
        'servers': [],
        'tags': [],
        'default_request_headers': {},
        'default_response_headers': {},
        'default_responses': {},
        'default_manual_parameters': [],
        'security_schemes': [
            {
                'type': 'apiKey',
                'in': 'header',
                'name': 'Authorization',
            },
        ],
    },
    'PREPEND_PATH': '',
    'MODELS_QUALIFIER': '',
    'SCHEMA_VIEW_AUTHENTICATION_CLASSES': rest_framework_settings.DEFAULT_AUTHENTICATION_CLASSES,
    'SCHEMA_VIEW_PERMISSION_CLASSES': rest_framework_settings.DEFAULT_PERMISSION_CLASSES,
    'OUTPUT_SCHEMA_ON_START': True,
    'OUTPUT_SCHEMA_FILE': None,
    'GENERATION_API_KEY': None,
    'SCHEMA_VIEW_URL_PATH': 'specification',
}

where DEFAULT_DESCRIPTION is:

[CloudBlue Connect](https://connect.cloudblue.com)
is a cloud end-to-end supply automation platform that joins service vendor and service provider efforts
to reach their business goals most effectively and efficiently. For this purpose, it provides a highly
customizable service to arrange various integrated business flows, including contract management, product
information flow, ordering and fulfillment, subscription management, and resource usage reporting.

Connect REST API provides you with the lowest-level access to the functionality of the Connect Platform.
All other integration methods, like our Portals, SDKs
and [Extensions](https://connect.cloudblue.com/view-help-doc?target=6) are built on top of the REST API layer.

Please visit our [Community Portal](https://connect.cloudblue.com/community) for more information.

These settings can be customized in your django settings module, for example:

DRF_CONNECT_DOCS = {
    'PREPEND_PATH': '/subscriptions',
    'MODELS_QUALIFIER': 'subscriptions',
    'SCHEMA_INFO': {
        'title': 'CloudBlue Connect Public API',
        'version': '19',
        'description': '**This is a description**',
        'termsOfService': 'https://corp.ingrammicro.com/Terms-of-Use.aspx',
        'contact': {
            'name': 'CloudBlue Connect Support',
            'url': 'https://connect.cloudblue.com/support',
            'email': 'support@cloudblue.com',
        },
        'license': {
            'name': 'CloudBlue Connect EULA',
            'url': 'https://connect.cloudblue.com/support',
        }
    },
    'SCHEMA': {
        'servers': [
            {
                'url': 'https://api.cnct.tech/public/v1',
                'description': 'Staging server',
            },
        ],
        'security_schemes': [
            {
                'type': 'apiKey',
                'in': 'header',
                'name': 'Authorization',
            },
        ],
        'tags': [
            {
                'name': 'General Collections',
                'description': 'here some endpoints',
            },
            {
                'name': 'Marketplace',
                'description': 'here agreements, contracts, listings etc',
                'external_docs': 'https://confluence.int.zone/display/CONNECT/Connect+Public+API',
            },
        ],
        'default_response_headers': {
            'list': {
                'Content-Range': {
                    'schema': {
                        'type': 'string',
                    },
                    'description': 'RQL RFC2616 limit offset pagination.',
                },
            },
            'get,put': {
                'X-Get-Is-Cool': {
                    'schema': {
                        'type': 'string',
                    },
                    'description': 'this header will be appendend to all responses to a get request.',
                },
            },
            '': {
                'X-Correlation-ID': {
                    'schema': {
                        'type': 'string',
                    },
                    'description': 'this header will be appendend to all responses.'
                },
            },
        },
        'default_responses': {
            'create,update': {
                '400': {
                    'content': {
                        'application/json': {
                            'schema': {
                                'type': 'object',
                                'properties': {
                                    'error_code': {
                                        'type': 'string',
                                    },
                                    'errors': {
                                        'type': 'array',
                                        'items': {
                                            'type': 'string',
                                        },
                                    },
                                },
                            },
                        },
                    },
                    'description': 'this response will be appended to all operations.',
                },
            },
        },
    },
}