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.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.
Raw data
{
"_id": null,
"home_page": "https://github.com/openedx/api-doc-tools",
"name": "edx-api-doc-tools",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "Django edx",
"author": "Open edX Project",
"author_email": "oscm@openedx.org",
"download_url": "https://files.pythonhosted.org/packages/bc/d8/8648374f7883cc46d1fb5b870f2d29a2876e1a04137197f840e83fab7c8f/edx_api_doc_tools-2.0.0.tar.gz",
"platform": null,
"description": "edX API Documentation Tools\n===========================\n\n|pypi| |CI| |codecov| |readthedocs| |pyversions| |license|\n\nA toolkit for documenting REST APIs that are created with `DRF`_.\n\n.. _DRF: https://www.django-rest-framework.org/\n\nThe tools use `drf-yasg`_ (DRF, yet another Swagger generator) to generate an\n`OpenAPI Specification`_, which is a .json/.yaml file that describes your API.\nAdditionally, this package makes it easy to configure your service to expose\ngenerated OpenAPI specification under `/api-docs.yaml` and to serve interactive\ndocumentation under `/api-docs`.\n\n.. _drf-yasg: https://github.com/axnsan12/drf-yasg\n.. _OpenAPI Specification: https://swagger.io/docs/specification/about/\n\nThis library was developed for use with `Open edX`_ services, but could be used\nto document any Django REST Framework API.\n\n.. _Open edX: https://open.edx.org/\n\n\nQuick Start\n-----------\n\nTo start using this tool in your project, see\n`Adding edx-api-doc-tools to your project <docs/adding.rst>`_.\n\nTo write docs using this tool, see\n`Writing API documentation <docs/writing.rst>`_.\n\n\nDocumentation\n-------------\n\nComphrehensive documentation is coming soon. For now, check out the `example/`\ndirectory, which shows a fake API using these tools to generate documentation.\n\nLicense\n-------\n\nThe code in this repository is licensed under the Apache Software License 2.0\nunless otherwise noted.\n\nPlease see `LICENSE.txt <LICENSE.txt>`_ for details.\n\nHow To Contribute\n-----------------\n\nContributions are very welcome. Please read `How To Contribute`__ for details.\nEven though they were written with `edx-platform` in mind, the guidelines\nshould be followed for all Open edX projects.\n\n__ https://github.com/openedx/.github/blob/master/CONTRIBUTING.md\n\nThe pull request description template should be automatically applied if you\nare creating a pull request from GitHub. Otherwise you can find it at\n`PULL_REQUEST_TEMPLATE.md`_.\n\nThe issue report template should be automatically applied if you are creating\nan issue on GitHub as well. Otherwise you can find it at `ISSUE_TEMPLATE.md`_.\n\n.. _PULL_REQUEST_TEMPLATE.md: .github/PULL_REQUEST_TEMPLATE.md\n.. _ISSUE_TEMPLATE.md: .github/ISSUE_TEMPLATE.md\n\nReporting Security Issues\n-------------------------\n\nPlease do not report security issues in public. Please email security@openedx.org.\n\nGetting Help\n------------\n\nHave 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.\n\n\n\n.. |pypi| image:: https://img.shields.io/pypi/v/edx-api-doc-tools.svg\n :target: https://pypi.python.org/pypi/edx-api-doc-tools/\n :alt: PyPI\n.. |CI| image:: https://github.com/openedx/api-doc-tools/workflows/Python%20CI/badge.svg?branch=master\n :target: https://github.com/openedx/api-doc-tools/actions?query=workflow%3A%22Python+CI%22\n :alt: CI\n.. |codecov| image:: http://codecov.io/github/edx/api-doc-tools/coverage.svg?branch=master\n :target: http://codecov.io/github/edx/api-doc-tools?branch=master\n :alt: Codecov\n.. |readthedocs| image:: https://readthedocs.org/projects/edx-api-doc-tools/badge/?version=latest\n :target: http://edx-api-doc-tools.readthedocs.io/en/latest/\n :alt: Documentation\n.. |pyversions| image:: https://img.shields.io/pypi/pyversions/edx-api-doc-tools.svg\n :target: https://pypi.python.org/pypi/edx-api-doc-tools/\n :alt: Supported\n.. |license| image:: https://img.shields.io/github/license/edx/api-doc-tools.svg\n :target: https://github.com/openedx/api-doc-tools/blob/master/LICENSE.txt\n :alt: License\n\n\nChange Log\n==========\n\n..\n All enhancements and patches to edx_api_doc_tools will be documented\n in this file. It adheres to the structure of http://keepachangelog.com/ ,\n but in reStructuredText instead of Markdown (for ease of incorporation into\n Sphinx documentation and the PyPI description).\n\n This project adheres to Semantic Versioning (http://semver.org/).\n\n.. There should always be an \"Unreleased\" section for changes pending release.\n\nUnreleased\n----------\n\n2.0.0 --- 2024-09-09\n--------------------\n* Drop support for Python 3.8\n* Add setuptools as a direct dependency\n\n1.8.0 --- 2024-02-29\n--------------------\n* Add support for python 3.11 and 3.12 support.\n* Removed django32 support.\n\n\n\n1.7.0 --- 2023-07-23\n--------------------\n\n* Switch from ``edx-sphinx-theme`` to ``sphinx-book-theme`` since the former is\n deprecated\n* Add support for Django 4.2\n\n1.6.0 --- 2022-02-11\n--------------------\n\n* Dropped support for django 2.2, 3.0, 3.1\n* Added support for Django 4.0\n\n1.5.0 --- 2021-07-19\n--------------------\n\n* Added support for django 3.0, 3.1 and 3.2\n\n1.4.3 --- 2021-07-15\n--------------------\n\n* Removed Django constraints from base.in\n\n1.4.2 --- 2021-01-08\n--------------------\n\n* Dropped python3.5 support.\n\n1.4.1 --- 2020-11-20\n--------------------\n\n* Updated the travis-badge in README.rst to point to travis-ci.com\n\n1.4.0 --- 2020-10-05\n--------------------\n\n* Adding option to include a body parameter in requests.\n\n1.3.2 --- 2020-09-23\n--------------------\n\n* Adding option to specify url patterns for generated docs.\n\n1.3.1 --- 2020-05-29\n--------------------\n\n* Removing caniusepython3 as it is no longer needed since python3 upgrade.\n\n1.3.0 --- 2020-04-30\n--------------------\n\n* Remove support for Django<2.2 and add support for python 3.8\n\n1.2.0 --- 2020-03-20\n--------------------\n\n* Added three new decorators for excluding endpoints from API documentation generation:\n\n * ``@exclude_schema``\n * ``@exclude_schema_for(method_name)``\n * ``@exclude_all_schemas``\n\n\n1.1.0 --- 2020-03-20\n--------------------\n\n* Compatibility with Django 2.1 and 2.2.\n\n\n1.0.3 --- 2020-01-31\n--------------------\n\n* Added documentation.\n\n\n1.0.2 --- 2020-01-17\n--------------------\n\n* First release on PyPI.\n",
"bugtrack_url": null,
"license": "Apache Software License 2.0",
"summary": "Tools for writing and generating API documentation for edX REST APIs",
"version": "2.0.0",
"project_urls": {
"Homepage": "https://github.com/openedx/api-doc-tools"
},
"split_keywords": [
"django",
"edx"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1334af6aa20e6e8971a5212b1a6482059a9a145feb3ba832304b516572369434",
"md5": "1a9a2e4f017cd48b1cff6ef8f2d9d9b2",
"sha256": "0b3807d545f24c4d71da9de8f12714ee0390b286bda3ae6c6ff880724e4a30ef"
},
"downloads": -1,
"filename": "edx_api_doc_tools-2.0.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "1a9a2e4f017cd48b1cff6ef8f2d9d9b2",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 14761,
"upload_time": "2024-09-11T13:11:51",
"upload_time_iso_8601": "2024-09-11T13:11:51.623752Z",
"url": "https://files.pythonhosted.org/packages/13/34/af6aa20e6e8971a5212b1a6482059a9a145feb3ba832304b516572369434/edx_api_doc_tools-2.0.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bcd88648374f7883cc46d1fb5b870f2d29a2876e1a04137197f840e83fab7c8f",
"md5": "548d174caa52cc2665bceb950c803a2a",
"sha256": "bc6e90031c1b6d5bbb3ac2e90c396e7dea2fa0a265fc3da4d6f43e35ee844730"
},
"downloads": -1,
"filename": "edx_api_doc_tools-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "548d174caa52cc2665bceb950c803a2a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 19714,
"upload_time": "2024-09-11T13:11:52",
"upload_time_iso_8601": "2024-09-11T13:11:52.967891Z",
"url": "https://files.pythonhosted.org/packages/bc/d8/8648374f7883cc46d1fb5b870f2d29a2876e1a04137197f840e83fab7c8f/edx_api_doc_tools-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-11 13:11:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "openedx",
"github_project": "api-doc-tools",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "edx-api-doc-tools"
}
JSON
