Document Web APIs made with Django Rest Framework

Manos Konstantinidis

Last update: Nov 20, 2022

Overview

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!

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

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
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

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

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 "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
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'

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

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

"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

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

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__

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
Not working for django=2.1.3 & djangorestframework==3.9.0

You need to change this:

URLPattern and URLResolver on line:3, line:26, line:29 in api_docs.py file.

pattern.pattern.regex on line:27 in api_docs.py file

pattern.pattern.regex.pattern on line:43

parent_pattern.pattern.regex.pattern on line:24, line:39 and line:40 in api_endpoint.py file.

Ref: https://github.com/encode/django-rest-framework/pull/5500
opened by ammarmallik 0
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)

0.0.11(Jun 4, 2016)
[Live API]: Fonts import, support both http and https (@cyriac, #87)

Source code(tar.gz)
Source code(zip)
0.0.10(May 26, 2016)
Use get_serializer_class for Views without serlaizer_class attribute (@EmadMokhtar, #92 )

Source code(tar.gz)
Source code(zip)
0.0.9(Mar 25, 2016)
Support for more types of ROOT_URLCONF

Move docs to MKDocs

Source code(tar.gz)
Source code(zip)
0.0.7(Feb 25, 2016)
Fix methods in Live API Endpoints (now compatible with Python 2.7)

Remove .<format> from urls

Fixed a bug that removes double slashes from the endpoint's url

Source code(tar.gz)
Source code(zip)
0.0.6(Jan 23, 2016)
Introducing Live API Endpoints - Test your endpoints from within the docs

Setting HIDDEN is now `HIDE_DOCS

Source code(tar.gz)
Source code(zip)
0.0.5(Dec 21, 2015)
Support both common types of ROOT_URLCONF

Source code(tar.gz)
Source code(zip)
0.0.4(Dec 20, 2015)
Allow templates overrides

More template blocks to be overridden

Improved MANIFEST.in

Exclude node_modules/

Source code(tar.gz)
Source code(zip)
0.0.3(Dec 20, 2015)
Fixes a bug where Django's collectstatic command was failing because of Glyphicons

Source code(tar.gz)
Source code(zip)
0.0.2(Dec 18, 2015)
Search between endpoint paths

Show docstring for each endpoint

Source code(tar.gz)
Source code(zip)
0.0.1(Dec 18, 2015)
First release of the project to pypi. Features include:

List all endpoints that inherit from DRF's APIView

Settings to hide docs view (ie. in Production)

Override Templates

Support for Python 2.7, 3.3, 3.4, 3.5

Support for Django 1.8, 1.9

Support for Django Rest Framework 3 and above

Source code(tar.gz)
Source code(zip)

Owner

Manos Konstantinidis

Engineering Manager at @FormidableLabs • Previously at The Times & The Sunday Times • author of gitify.io

GitHub https://www.drfdocs.com/

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.

1.8k Jan 4, 2023

Scaffold django rest apis like a champion 🚀

scaffold django rest apis like a champion ??

133 Jan 5, 2023

A JSON Web Token authentication plugin for the Django REST Framework.

Simple JWT Abstract Simple JWT is a JSON Web Token authentication plugin for the Django REST Framework. For full documentation, visit django-rest-fram

3.3k Jan 4, 2023

Um aplicativo de usuários feito em Django REST Framework, nesse aplicativo eu modifiquei o modelo padrão de user do Django, adicionando campos personalizados e login com email e senha, também desenvolvi funcionalidades para a API e testes automatizados, para conferir tudo leia o README abaixo!

App de Usuários Esse é um app de usuários personalizado feito em Django REST Framework, nele eu modifiquei o model padrão de users do Django, adiciona