Metadata-Version: 2.4
Name: edx-api-doc-tools
Version: 2.1.2
Summary: Tools for writing and generating API documentation for edX REST APIs
Home-page: https://github.com/openedx/api-doc-tools
Author: Open edX Project
Author-email: oscm@openedx.org
License: Apache Software License 2.0
Keywords: Django edx
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Description-Content-Type: text/x-rst
License-File: LICENSE.txt
Requires-Dist: Django
Requires-Dist: djangorestframework>=3.2.0
Requires-Dist: drf-yasg
Requires-Dist: setuptools
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: summary

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@openedx.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
----------

2.1.2 - 2026-01-39
------------------
* Fix builds to PyPI

2.1.1 - 2026-01-39
------------------
* Fix make upgrade, update dependencies

2.1.0 - 2025-04-18
------------------
* Added Support for ``django 5.2``.

2.0.0 --- 2024-09-09
--------------------
* Drop support for Python 3.8
* Add setuptools as a direct dependency

1.8.0 --- 2024-02-29
--------------------
* Add support for python 3.11 and 3.12 support.
* Removed django32 support.

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.
