edx-api-doc-tools 1.0.2

Tools for writing and generating API documentation for edX REST APIs

A toolkit for documenting REST APIs that are created with DRF.

The tools use drf-yasg (DRF, yet another Swagger generator) to generate an OpenAPI Specification, which is a .json/.yaml file that describes your API. Additionally, this package makes it easy to configure your service to expose generated OpenAPI specification under /api-docs.yaml and to serve interactive documentation under /api-docs.

This library is intended for use with Open edX services, but could be used to document any Django REST Framework API.

Quick Start

First, add edx-api-doc-tools to your requirements and install it into your environment.

Next, add the following to your list of installed apps in Django settings:

INSTALLED_APPS = (
    ... # your other installed apps
    drf_yasg,
    edx_api_doc_tools,
)

Then, in urls.py:

...
from edx_api_doc_tools import make_api_info, make_docs_urls
...
api_info = make_api_info(title="Registrar API", version="v2")
urlpatterns += make_docs_urls(api_info)

Your should now be able to load the Swagger UI in a browser at https://${your_service}/api-docs. Note that by default, documentation is only generated for views under the root path /api. Generation for other views is possible but requires some extra configuration.

Finally, you can enrich the generated documentation:

...
from edx_api_doc_tools import parameter, schema
...
class MyView(APIView):

    @schema(
        parameters=[
            parameter('min_date', str, 'Filter response by minimum date.'),
        ],
        responses={
            403: 'User lacks required permission.'
            404: 'Resource does not exist.'
            # Note that 2xx response is automatically figured out by drf-yasg,
            # with reponse schema coming from the serializer, if declared.
        },
    )
    def get(self, request):
        """
        Get the resource.

        This docstring will be used in the OpenAPI spec, and *supports Markdown!*
        """
        ...

Documentation

Comphrehensive documentation is coming soon. For now, check out the example/ directory, which shows a fake API using these tools to generate documentation.

License

The code in this repository is licensed under the Apache Software License 2.0 unless otherwise noted.

Please see LICENSE.txt for details.

How To Contribute

Contributions are very welcome.

Please read How To Contribute for details.

Even though they were written with edx-platform in mind, the guidelines should be followed for Open edX code in general.

The pull request description template should be automatically applied if you are creating a pull request from GitHub. Otherwise you can find it at PULL_REQUEST_TEMPLATE.md.

The issue report template should be automatically applied if you are creating an issue on GitHub as well. Otherwise you can find it at ISSUE_TEMPLATE.md.

Reporting Security Issues

Please do not report security issues in public. Please email [e-mail].

Getting Help

Have a question about this repository, or about Open edX in general? Please refer to this list of resources if you need any assistance.

Change Log

Unreleased

1.0.2 — 2020-01-17

Added

• First release on PyPI.