edX API Documentation Tools

|pypi| |CI| |codecov| |readthedocs| |pyversions| |license|

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

.. _DRF: https://www.django-rest-framework.org/

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.

.. _drf-yasg: https://github.com/axnsan12/drf-yasg .. _OpenAPI Specification: https://swagger.io/docs/specification/about/

This library was developed for use with Open edX_ services, but could be used to document any Django REST Framework API.

.. _Open edX: https://open.edx.org/

Quick Start

To start using this tool in your project, see Adding edx-api-doc-tools to your project <docs/adding.rst>_.

To write docs using this tool, see Writing API documentation <docs/writing.rst>_.

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 <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 all Open edX projects.

__ https://github.com/openedx/.github/blob/master/CONTRIBUTING.md

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_.

.. _PULL_REQUEST_TEMPLATE.md: .github/PULL_REQUEST_TEMPLATE.md .. _ISSUE_TEMPLATE.md: .github/ISSUE_TEMPLATE.md

Reporting Security Issues

Please do not report security issues in public. Please email security@edx.org.

Getting Help

Have a question about this repository, or about the Open edX project in general? Please refer to this list of resources <https://open.edx.org/getting-help>_ if you need any assistance.

.. |pypi| image:: https://img.shields.io/pypi/v/edx-api-doc-tools.svg :target: https://pypi.python.org/pypi/edx-api-doc-tools/ :alt: PyPI .. |CI| image:: https://github.com/openedx/api-doc-tools/workflows/Python%20CI/badge.svg?branch=master :target: https://github.com/openedx/api-doc-tools/actions?query=workflow%3A%22Python+CI%22 :alt: CI .. |codecov| image:: http://codecov.io/github/edx/api-doc-tools/coverage.svg?branch=master :target: http://codecov.io/github/edx/api-doc-tools?branch=master :alt: Codecov .. |readthedocs| image:: https://readthedocs.org/projects/edx-api-doc-tools/badge/?version=latest :target: http://edx-api-doc-tools.readthedocs.io/en/latest/ :alt: Documentation .. |pyversions| image:: https://img.shields.io/pypi/pyversions/edx-api-doc-tools.svg :target: https://pypi.python.org/pypi/edx-api-doc-tools/ :alt: Supported .. |license| image:: https://img.shields.io/github/license/edx/api-doc-tools.svg :target: https://github.com/openedx/api-doc-tools/blob/master/LICENSE.txt :alt: License

Change Log

.. All enhancements and patches to edx_api_doc_tools will be documented in this file. It adheres to the structure of http://keepachangelog.com/ , but in reStructuredText instead of Markdown (for ease of incorporation into Sphinx documentation and the PyPI description).

This project adheres to Semantic Versioning (http://semver.org/).

.. There should always be an "Unreleased" section for changes pending release.

Unreleased

1.7.0 --- 2023-07-23

• Switch from edx-sphinx-theme to sphinx-book-theme since the former is deprecated
• Add support for Django 4.2

1.6.0 --- 2022-02-11

• Dropped support for django 2.2, 3.0, 3.1
• Added support for Django 4.0

1.5.0 --- 2021-07-19

• Added support for django 3.0, 3.1 and 3.2

1.4.3 --- 2021-07-15

• Removed Django constraints from base.in

1.4.2 --- 2021-01-08

• Dropped python3.5 support.

1.4.1 --- 2020-11-20

• Updated the travis-badge in README.rst to point to travis-ci.com

1.4.0 --- 2020-10-05

• Adding option to include a body parameter in requests.

1.3.2 --- 2020-09-23

• Adding option to specify url patterns for generated docs.

1.3.1 --- 2020-05-29

• Removing caniusepython3 as it is no longer needed since python3 upgrade.

1.3.0 --- 2020-04-30

• Remove support for Django<2.2 and add support for python 3.8

1.2.0 --- 2020-03-20

• Added three new decorators for excluding endpoints from API documentation generation:

  • @exclude_schema
  • @exclude_schema_for(method_name)
  • @exclude_all_schemas

1.1.0 --- 2020-03-20

• Compatibility with Django 2.1 and 2.2.

1.0.3 --- 2020-01-31

• Added documentation.

1.0.2 --- 2020-01-17

• First release on PyPI.