Document Web APIs made with Django Rest Framework

Overview

DRF Docs travis codecov pypi slack

Document Web APIs made with Django Rest Framework. View Demo

Contributors Wanted: Do you like this project? Using it? Let's make it better!

DRFdocs

Supports

  • Python (2.7, 3.3, 3.4, 3.5)
  • Django (1.8, 1.9)
  • Django Rest Framework (3+)

Documentation - Table of contents

Development & Demo Project

If you are looking to develop this package with one of your own django projects:

pyvenv env
env/bin/pip install -r requirements.txt
pip install -e ~/Projects/drf-docs/

If you want to use the demo app to work on this package: Included in this repo you can find the demo project(at /demo). It is a project with Django & Django Rest Framework that will allow you to work with this project. For more information on how you can set it up please check the README.md of the demo project.

For more information visit the docs.

Installation

Install using pip:

pip install drfdocs

Add 'rest_framework_docs' to your INSTALLED_APPS setting:

INSTALLED_APPS = (
    ...
    'rest_framework_docs',
)

Finally include the rest_framework_docs urls in your urls.py:

urlpatterns = [
    ...
    url(r'^docs/', include('rest_framework_docs.urls')),
]

Settings

You can find detailed information about the package's settings at the docs.

REST_FRAMEWORK_DOCS = {
    'HIDE_DOCS': True  # Default: False
}

Credits

First of all thanks to the Django core team and to all the contributors of Django REST Framework for their amazing work. Also I would like to thank Marc Gibbons for his django-rest-framework-docs project. Both projects share the same idea, it is just that Marc's is not maintained anymore and does not support DRF 3+ & Python 3.

Comments
  • Added markdown support for endpoint docstrings

    Added markdown support for endpoint docstrings

    I recently started using drfdocs and wanted to add some documentation onto each view I have. Some extra documentation I have needed to be formatted (line breaks etc) and was longer than a single line.

    This simple change allows reStructuredText to be added to a DRF View docstring, meaning users can add structured documentation that can be viewed when clicking on each API on the docs page.

    opened by mikeengland 13
  • Nested serializers support

    Nested serializers support

    Take a look at this.

    We added:

    • An example for nested serializers in the demo app.
    • Support for nested serializer in nested serializer (recursive)
    • User friendly interface for the nested serializer data.

    Things that we are going to add in a separate pull request:

    • Support for Nested Serialization in Live API Endpoints.

    Authors: Me and @Ivo-Donchev :panda_face: :beers:

    enhancement release 
    opened by Ivaylo-Bachvarov 10
  • "urls doesn't look like a module path" for settings.ROOT_URLCONF

    Heyoo, thanks so much for releasing this!

    I seem to be having a problem based on this setting: ROOT_URLCONF = 'urls'

      File "/Users/eric/.virtualenvs/image_first/lib/python3.5/site-packages/rest_framework_docs/views.py", line 17, in get_context_data
        docs = ApiDocumentation()
      File "/Users/eric/.virtualenvs/image_first/lib/python3.5/site-packages/rest_framework_docs/api_docs.py", line 12, in __init__
        root_urlconf = import_string(settings.ROOT_URLCONF)
      File "/Users/eric/.virtualenvs/image_first/lib/python3.5/site-packages/django/utils/module_loading.py", line 18, in import_string
        six.reraise(ImportError, ImportError(msg), sys.exc_info()[2])
      File "/Users/eric/.virtualenvs/image_first/lib/python3.5/site-packages/django/utils/six.py", line 685, in reraise
        raise value.with_traceback(tb)
      File "/Users/eric/.virtualenvs/image_first/lib/python3.5/site-packages/django/utils/module_loading.py", line 15, in import_string
        module_path, class_name = dotted_path.rsplit('.', 1)
    ImportError: urls doesn't look like a module path
    

    Changing to this works: ROOT_URLCONF = 'src.urls'

    opened by ckcollab 9
  • Create setup.cfg

    Create setup.cfg

    when updating rpm's from django-rest-framework-docs to drfdocs the rpm fails to update because of conflicting files, this obsolets should tell yum/dnf to first remove the old rpm

    opened by JensTimmerman 5
  • Use get_serializer_class for Views without serlaizer_class attribute

    Use get_serializer_class for Views without serlaizer_class attribute

    Sometimes View won't has serliazer_class as DRF documentations, so it's nice to get the serializer class using get_serlizer_class if there is no serliazer_class

    release 
    opened by EmadMokhtar 5
  • Middle slash removed by

    Middle slash removed by "replace"

    In an DRF router endpoint I'm seeing the following behavior:

    url(r'^api/v1/', include(router.urls)), # becomes "apiv1" in DRF docs output
    

    Not sure exactly sure why slashes are being replaced on this line, but perhaps a strip('/') than replace('/','')would be more appropriate, as that would preserve slashes in the middle, like I need.

    https://github.com/ekonstantinidis/django-rest-framework-docs/blob/9a85323c4147ec4ebb754a8b0373c956ee89b821/rest_framework_docs/api_endpoint.py#L1

    Happy to make a PR

    bug 
    opened by philngo 5
  • Small improvements

    Small improvements

    • Fixing displayed URL by using pattern instead of name_parent regex (for namespaced URLs mainly)
    • Distinction between custom API views and RESTFul APIs generated through models and routers
    • Adding possibility to use app_name in URL patterns for API organisation
    • Adding an URL to filter APIs by app_name or name_parent
    enhancement work in progress 
    opened by debnet 5
  • AttributeError - module 'urls' has no attribute 'urls'

    AttributeError - module 'urls' has no attribute 'urls'

    My understanding is that there are two common settings of ROOT_URLCONF people use. One is the default ROOT_URLCONF = '' value, and the second is ROOT_URLCONF = 'urls'. This project seems to fail if you use the latter (or at least it did for me). Changing that line to self.get_all_view_names(root_urlconf.urlpatterns) worked but it would be best to fix in the project.

    The root urlconf can also be overridden at runtime via middleware so I think this urls module loading should perhaps be moved into the get_endpoints method or the value of that setting should be passed into the ApiDocumentation object on init.

    Nice project BTW. :-)

    bug 
    opened by poswald 5
  • add viewset support

    add viewset support

    This is how I would solve issue https://github.com/ekonstantinidis/django-rest-framework-docs/issues/58. I think that using the rest framework router, which provides all the magic, is probably the cleanest way.

    enhancement review needed 
    opened by sebdiem 4
  • Django 1.9 incompatibilities

    Django 1.9 incompatibilities

    "C:\Program Files (x86)\PyCharm\bin\runnerw.exe" D:\VirtualEnvs\nouvelleoffre\Scripts\python.exe D:/Git/nouvelleoffre-back/manage.py runserver 8000
    Traceback (most recent call last):
      File "D:/Git/nouvelleoffre-back/manage.py", line 10, in <module>
        execute_from_command_line(sys.argv)
      File "D:\VirtualEnvs\nouvelleoffre\lib\site-packages\django\core\management\__init__.py", line 351, in execute_from_command_line
        utility.execute()
      File "D:\VirtualEnvs\nouvelleoffre\lib\site-packages\django\core\management\__init__.py", line 343, in execute
        self.fetch_command(subcommand).run_from_argv(self.argv)
      File "D:\VirtualEnvs\nouvelleoffre\lib\site-packages\django\core\management\__init__.py", line 177, in fetch_command
        commands = get_commands()
      File "C:\Python34\lib\functools.py", line 448, in wrapper
        result = user_function(*args, **kwds)
      File "D:\VirtualEnvs\nouvelleoffre\lib\site-packages\django\core\management\__init__.py", line 72, in get_commands
        for app_config in reversed(list(apps.get_app_configs())):
      File "D:\VirtualEnvs\nouvelleoffre\lib\site-packages\django\apps\registry.py", line 137, in get_app_configs
        self.check_apps_ready()
      File "D:\VirtualEnvs\nouvelleoffre\lib\site-packages\django\apps\registry.py", line 124, in check_apps_ready
        raise AppRegistryNotReady("Apps aren't loaded yet.")
    django.core.exceptions.AppRegistryNotReady: Apps aren't loaded yet.
    

    Everything works fine when removing "rest_framework_docs" from INSTALLED_APPS.

    Thanks.

    invalid 
    opened by debnet 4
  • Allow overriding script in template block

    Allow overriding script in template block

    Hello,

    Thanks for the awesome library. I would like to have the ability to extend the scripts so I'm just wrapping it in a template block. Hope it's ok.

    opened by limdauto 3
  • Need to add token field in header

    Need to add token field in header

    Hi guys, Recently i implemented drfdocs in my project, Everything is working good but i need to add token field in header for all request, Please help me out here.

    opened by ashishbhardwaj0506 0
  • api_endpoint __get_permissions_class__ missing __name__

    api_endpoint __get_permissions_class__ missing __name__

    with DRF 3.9.1 we have errors for custom permissions with following exception AttributeError: OperandHolder instance has no attribute '__name__'

    the self.pattern.callback.cls.permission_classes seems to return a mix of classes and instances (e.g. for a subclass of DjangoObjectPermissions)

    opened by stdweird 0
  • RegexURLPattern and RegexURLResolver must be changed to URLPattern and URLResolver respectively

    RegexURLPattern and RegexURLResolver must be changed to URLPattern and URLResolver respectively

    Not working for django=2.1.3 & djangorestframework==3.9.0

    You need to change this:

    Ref: https://github.com/encode/django-rest-framework/pull/5500

    opened by ammarmallik 0
  • Error in import

    Error in import

    Hi I try use this solution to generate my api docs. I installed it with pip and add it name in INSTALLED_APPS, but, when i running the server, that error appears:

    File "/my_pc/envs/my_project/lib/python3.5/site-packages/rest_framework_docs/api_docs.py", line 3, in from django.core.urlresolvers import RegexURLResolver, RegexURLPattern ImportError: No module named 'django.core.urlresolvers'

    Anyone have any ideia for fix it?

    I using: Django==2.0.7 djangorestframework==3.8.2 drfdocs==0.0.11

    opened by HandBoy 4
Releases(0.0.11)
Owner
Manos Konstantinidis
Engineering Manager at @FormidableLabs • Previously at The Times & The Sunday Times • author of gitify.io
Manos Konstantinidis
Estudo e desenvolvimento de uma API REST

Estudo e desenvolvimento de uma API REST 🧑‍💻 Tecnologias Esse projeto utilizará as seguintes tecnologias: Git Python Flask DBeaver Vscode SQLite 🎯

Deusimar 7 May 30, 2022
Django app for handling the server headers required for Cross-Origin Resource Sharing (CORS)

django-cors-headers A Django App that adds Cross-Origin Resource Sharing (CORS) headers to responses. This allows in-browser requests to your Django a

Adam Johnson 4.8k Jan 05, 2023
BreakFastApi 🍣 🍔 🍕 The most delicious API on the web

BreakFastApi 🍣 🍔 🍕 The most delicious API on the web. Just send a request and you'll receive the most mouth watering dish recipe with estimated coo

Mariia Sizova 156 Nov 19, 2022
A RESTful way to use your Notion tables as a database.

rest-notion-db A RESTful way to use your Notion tables as a database. Use-cases Form submissions or frontend websites, use one database that

Oorjit Chowdhary 42 Dec 27, 2022
A light REST library for Django.

django-nap Read The Docs: https://django-nap.readthedocs.io/en/latest/ Change log: https://django-nap.readthedocs.io/en/latest/changelog.html An API l

Curtis Maloney 223 Dec 07, 2022
Web APIs for Django. 🎸

Django REST framework Awesome web-browsable Web APIs. Full documentation for the project is available at https://www.django-rest-framework.org/. Fundi

Encode 24.7k Jan 04, 2023
Authentication for Django Rest Framework

Dj-Rest-Auth Drop-in API endpoints for handling authentication securely in Django Rest Framework. Works especially well with SPAs (e.g React, Vue, Ang

Michael 1.1k Dec 28, 2022
Django queries

Djaq Djaq - pronounced “Jack” - provides an instant remote API to your Django models data with a powerful query language. No server-side code beyond t

Paul Wolf 53 Dec 12, 2022
REST API with Flask. No data persistence.

Flask REST API Python 3.9.7 The Flask experience, without data persistence :D First, to install all dependencies: python -m pip install -r requirement

Luis Quiñones Requelme 1 Dec 15, 2021
Built on Django Rest Framework, to provide with command execution on linux terminal

Built on Django Rest Framework, to provide with command execution on linux terminal

1 Oct 31, 2021
Django Ninja is a web framework for building APIs with Django and Python 3.6+ type hints.

💨 Fast, Async-ready, Openapi, type hints based framework for building APIs

Vitaliy Kucheryaviy 3.8k Jan 04, 2023
RESTful Todolist API

RESTful Todolist API GET todolist/ POST todolist/ {"desc" : "Description of task to do"} DELETE todolist/int:id PUT todolist/int:id Requirements D

Gabriel Tavares 5 Dec 20, 2021
A small repository of projects built in my course, REST APIs with Flask and Python.

A small repository of projects built in my course, REST APIs with Flask and Python.

Teclado 1k Jan 05, 2023
Eazytraining - Simple application to show how to query API from webapp

student-list Eazytraining - Simple application to show how to query API from webapp This repo is a simple application to list student with a webserver

⚡Christophe FREIJANES 2 Nov 15, 2021
DSpace REST API Client Library

DSpace Python REST Client Library This client library allows Python 3 scripts (Python 2 probably compatible but not officially supported) to interact

The Library Code GmbH 10 Nov 21, 2022
Sanic-RESTPlus is an extension for Sanic that adds support for quickly building REST APIs.

Sanic RestPlus Sanic-RESTPlus is an extension for Sanic that adds support for quickly building REST APIs. Sanic-RESTPlus encourages best practices wit

Ashley Sommer 106 Oct 14, 2022
Kong API Manager with Prometheus And Splunk

API Manager Stack Run Kong Server + Konga + Prometheus + Grafana + API & DDBB + Splunk Clone the proyect and run docker-compose up

Santiago Fernandez 82 Nov 26, 2022
The no-nonsense, minimalist REST and app backend framework for Python developers, with a focus on reliability, correctness, and performance at scale.

The Falcon Web Framework Falcon is a reliable, high-performance Python web framework for building large-scale app backends and microservices. It encou

Falconry 9k Jan 03, 2023
Python bindings for Podman's RESTful API

podman-py This python package is a library of bindings to use the RESTful API of Podman. It is currently under development and contributors are welcom

Containers 142 Jan 06, 2023
BloodDonors: Built using Django REST Framework for the API backend and React for the frontend

BloodDonors By Daniel Yuan, Alex Tian, Aaron Pan, Jennifer Yuan As the pandemic raged, one of the side effects was an urgent shortage of blood donatio

Daniel Yuan 1 Oct 24, 2021