Skip to main content

Tools for writing and generating API documentation for edX REST APIs

Project description

edX API Documentation Tools

PyPI Travis Codecov Documentation Supported License

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 was developed for use with Open edX services, but could be used to document any Django REST Framework API.

Quick Start

To start using this tool in your project, see Adding edx-api-doc-tools to your project.

To write docs using this tool, see Writing API documentation.

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

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 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 if you need any assistance.

Change Log

Unreleased

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for edx-api-doc-tools, version 1.4.0
Filename, size File type Python version Upload date Hashes
Filename, size edx_api_doc_tools-1.4.0-py2.py3-none-any.whl (14.5 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size edx-api-doc-tools-1.4.0.tar.gz (13.5 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page