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
Allows simplified Python interaction with Rapid7's InsightIDR REST API.

InsightIDR4Py Allows simplified Python interaction with Rapid7's InsightIDR REST API. InsightIDR4Py allows analysts to query log data from Rapid7 Insi

Micah Babinski 8 Sep 12, 2022
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
Integrate GraphQL into your Django project.

Graphene-Django A Django integration for Graphene. 💬 Join the community on Slack Documentation Visit the documentation to get started! Quickstart For

GraphQL Python 4k Dec 31, 2022
Little Library API REST

Little Library API REST py 3.10 The only one requeriment it's to have Flask installed.

Luis Quiñones Requelme 1 Dec 15, 2021
A RESTful whois

whois-rest A RESTful whois. Installation $ pip install poetry $ poetry install $ uvicorn app:app INFO: Started server process [64616] INFO: W

Manabu Niseki 4 Feb 19, 2022
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
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
Build a Backend REST API with Python & Django

Build a Backend REST API with Python & Django Skills Python Django djangorestframework Aws Git Use the below Git commands in the Windows Command Promp

JeonSoohyun a.k.a Edoc.. 1 Jan 25, 2022
Document Web APIs made with Django Rest Framework

DRF Docs Document Web APIs made with Django Rest Framework. View Demo Contributors Wanted: Do you like this project? Using it? Let's make it better! S

Manos Konstantinidis 626 Nov 20, 2022
REST API framework designed for human beings

Eve Eve is an open source Python REST API framework designed for human beings. It allows to effortlessly build and deploy highly customizable, fully f

eve 6.6k Jan 04, 2023
Extensions for Django REST Framework

Extensions for Django REST Framework

aiden 6 Dec 27, 2022
simple api build with django rest framework

Django Rest API django-rest-framework Employees management simple API in this project wrote test suites for endpoints wrote simple doc string for clas

OMAR.A 1 Mar 31, 2022
Generate Views, Serializers, and Urls for your Django Rest Framework application

DRF Generators Writing APIs can be boring and repetitive work. Don't write another CRUDdy view in Django Rest Framework. With DRF Generators, one simp

Tobin Brown 332 Dec 17, 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
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
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
A minimalistic manga reader for desktop built with React and Django

smanga A minimalistic manga reader/server for serving local manga images on desktop browser. Provides a two-page view layout just as reading a physica

Padam Upreti 13 Sep 24, 2022
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
RESTler is the first stateful REST API fuzzing tool for automatically testing cloud services through their REST APIs and finding security and reliability bugs in these services.

RESTler is the first stateful REST API fuzzing tool for automatically testing cloud services through their REST APIs and finding security and reliability bugs in these services.

Microsoft 1.8k Jan 04, 2023
Country-specific Django helpers, to use in Django Rest Framework

django-rest-localflavor Country-specific serializers fields, to Django Rest Framework Documentation (soon) The full documentation is at https://django

Gilson Filho 19 Aug 30, 2022