{"id":13813104,"url":"https://github.com/iMakedonsky/drf-autodocs","last_synced_at":"2025-05-14T22:31:51.840Z","repository":{"id":44206953,"uuid":"77279434","full_name":"iMakedonsky/drf-autodocs","owner":"iMakedonsky","description":"Ultimately automated DRF documentation rendering(UNMAINTAINED)","archived":true,"fork":false,"pushed_at":"2019-11-19T20:15:24.000Z","size":1041,"stargazers_count":86,"open_issues_count":20,"forks_count":14,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-05-12T05:18:12.682Z","etag":null,"topics":["api","api-documentation","django","django-rest","django-rest-framework","documentation","documentation-generator","documentation-tool","rest-api"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iMakedonsky.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-12-24T11:09:28.000Z","updated_at":"2024-01-12T05:31:51.000Z","dependencies_parsed_at":"2022-08-19T20:01:00.946Z","dependency_job_id":null,"html_url":"https://github.com/iMakedonsky/drf-autodocs","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iMakedonsky%2Fdrf-autodocs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iMakedonsky%2Fdrf-autodocs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iMakedonsky%2Fdrf-autodocs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iMakedonsky%2Fdrf-autodocs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iMakedonsky","download_url":"https://codeload.github.com/iMakedonsky/drf-autodocs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254239723,"owners_count":22037758,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-documentation","django","django-rest","django-rest-framework","documentation","documentation-generator","documentation-tool","rest-api"],"created_at":"2024-08-04T04:01:03.283Z","updated_at":"2025-05-14T22:31:46.253Z","avatar_url":"https://github.com/iMakedonsky.png","language":"HTML","funding_links":[],"categories":["HTML"],"sub_categories":[],"readme":"*THIS REPO IS NO LONGER MAINTAINED. PLEASE CONSIDER OTHER AUTOMATED DOCUMENTATION PACKAGES*\n\n# Django REST framework auto docs\nAutomated api documentation renderer\n\n### Features:\n\n * optional response_serializer_class, if output serializer is different from input serializer\n * fully-documented functional views\n * tree-like structure\n * Docstrings:\n  * markdown\n  * preserve space \u0026 newlines\n  * formatting with nice syntax\n * Fields:\n  * different fields for request/response, based on read-/write-only attributes and whether response_serializer_class presented or not\n  * choices rendering\n  * help_text rendering (to specify SerializerMethodField output, etc)\n * Endpoint properties:\n  * filter_backends\n  * authentication_classes\n  * permission_classes\n  * extra url params(GET params)\n\n### What isn't supported yet:\n\n * viewsets\n * possibility to try in browser\n\n\n# Samples\n\n#### Whole structure:\n\n![whole structure](http://joxi.ru/52aBGNI4k3oyA0.jpg)\n\n#### Single node:\n\n![single node](http://joxi.ru/E2ppYWh94VdV2Y.jpg)\n\n#### Choices:\n\n![choices](http://joxi.ru/D2PdaVspB1M423.jpg)\n\n#### Nested items:\n\n![nested items](http://joxi.ru/vAWOkRt1BKY4AW.jpg)\n\n#### Docstring formatting:\n```python\n@format_docstring(request_example, response_example=response_example)\nclass BookReadUpdateHandler(RetrieveUpdateAPIView):\n    \"\"\"\n    Wow, this magic decorator allows us to:\n        1) Keep clean \u0026 short docstring\n        2) Insert additional data in it, like request/response examples\n\n    Request: {}\n    Response: {response_example}\n    \"\"\"\n```\n\n![help text](http://joxi.ru/VrwzKWSO4YekAX.jpg)\n\n\n# Installation\n\nIn virtualenv:\n\n    pip install drf_autodocs\n\nIn settings:\n\n    INSTALLED_APPS = [\n        ...\n        'drf_autodocs',\n        ...\n    ]\n\nIn your urls:\n\n    urlpatterns = [\n        ...\n        url(r'^', include('drf_autodocs.urls')),\n    ]\n\n\nThat's already enough for swagger-like docs,\nresult available on\n\n`localhost:8000/docs/`\n\nIf you want functional views support and some more features, read below.\n\n# Usage\n\n### Tree-like structure\n\nTree-like structure is built from url prefixes. To make your endpoints grouped by some\ncategory, you must include your urls within other url. There are, generally, 2 ways to achieve it:\n\nExample 1:\n\n```python\nuniversity_urlpatterns = [\n    url(r'^lecturers/', university_views.LecturersHandler.as_view(), name='lecturers'),\n    url(r'^lecturers/(?P\u003cpk\u003e\\d+)/$', university_views.LecturerUpdateHandler.as_view(), name='lecturer_read_update'),\n    url(r'^universities/', university_views.UniversitiesHandler.as_view(), name='universities'),\n]\n\nurlpatterns = [\n    url(r'^library/', include(library_urlpatterns, namespace='library')),\n    url(r'^university/', include(university_urlpatterns, namespace='university')),\n]\n```\n\nExample 2:\n```python\nurlpatterns = [\n    url(r'^library/', include(library_urlpatterns, namespace='library')),\n    url(r'^university/', include([\n        url(r'^lecturers/', university_views.LecturersHandler.as_view(), name='lecturers'),\n        url(r'^lecturers/(?P\u003cpk\u003e\\d+)/$', university_views.LecturerUpdateHandler.as_view(), name='lecturer_read_update'),\n        url(r'^universities/', university_views.UniversitiesHandler.as_view(), name='universities')\n    ], namespace='university')),\n]\n```\n\n\n### Response serializer class\nSay you have a view like this:\n```python\nclass BookReadUpdateHandler(RetrieveUpdateAPIView):\n    serializer_class = BookUpdateSerializer\n    queryset = Book.objects.all()\n```\n\nAnd say this serializers' input is different from output:\n```python\nclass BookUpdateSerializer(serializers.ModelSerializer):\n    class Meta:\n        fields = ('name', 'author')\n        model = Book\n\n    def to_representation(self, instance):\n        return LibrarySerializer(instance.library)\n```\n\nNow to know what return format is, one must make a request.\nThis package simplifies it via:\n\n`response_serializer_class = YourSerializer`\n\nNow your view looks like:\n```python\nclass BookReadUpdateHandler(RetrieveUpdateAPIView):\n    \"\"\"\n    Shiny and nice docstring, which:\n        1) allows formatting\n        2) `allows markdown`\n    \"\"\"\n    serializer_class = BookUpdateSerializer\n    response_serializer_class = LibrarySerializer\n    queryset = Book.objects.all()\n```\n\n\n### Docstring formatting in class-based views\n\n```python\nfrom .request_response_examples import request_example, response_example\nfrom drf_autodocs.decorators import format_docstring\n\n\n@format_docstring(request_example, response_example=response_example)\nclass BookReadUpdateHandler(RetrieveUpdateAPIView):\n    \"\"\"\n    Wow, this magic decorator allows us to:\n        1) Keep clean \u0026 short docstring\n        2) Insert additional data in it, like request/response examples\n\n    Request: {}\n    Response: {response_example}\n    \"\"\"\n    serializer_class = BookUpdateSerializer\n    response_serializer_class = LibrarySerializer\n    queryset = Book.objects.all()\n```\n\n\n### Extra URL(GET) parameters\nPlease think twice before using such parameters, as they might be unneeded.\n\nBut if you really need them, here you go:\n\n```python\nclass LibrariesHandler(ListCreateAPIView):\n    \"\"\"\n    Shiny and nice docstring, which:\n        1) allows formatting\n        2) `allows markdown`\n    \"\"\"\n    extra_url_params = (('show_all', 'Bool', 'if True returns all instances and only 5 otherwise'),\n                        ('some_extra_param', 'Integer', 'Something more to be included there'))\n```\n\nResults in:\n\n![extra_url_params](http://joxi.ru/E2ppYWh9GMzJ2Y.jpg)\n\n\n### Function-based views\n\nFor functional views, decorate them with.\n\n`drf_autodocs.decorators.document_func_view`\n\nNow you can insert into view via kwargs:\n\n * serializer_class\n * response_serializer_class\n * filter_backends\n * authentication_classes\n * permission_classes\n * doc_format_args\n * doc_format_kwargs\n\nNow it should look like:\n```python\nfrom drf_autodocs.decorators import document_func_view\n\nformat_args = ['\"This string\\nwas inserted\"',]\n\n@document_func_view(serializer_class=BookSerializer,\n                    response_serializer_class=LibrarySerializer,\n                    doc_format_args=format_args)\n@api_view(['GET', 'POST', 'DELETE'])\ndef hello_world(request):\n    \"\"\"\n    Works for `functional` views too!\n        Yeah, that thing rocks!\n        And allows formatting {}\n    \"\"\"\n    return Response('hello_world response')\n```\n\n### Help text\n\nThis package uses default DRF field attribute `help_text`\nIf you're using `ModelSerializer`, and model field got `help_text` attr, it will be\ntransferred to your serializers' field automatically.\n\nExample:\n\n```python\nfrom rest_framework import serializers\n\nhas_books = serializers.SerializerMethodField(help_text='returns Bool')\n```\n\nNote that specifying help_text on serializers' field overrides the one from model\n\n\n# Customization\nTo change application look \u0026 feel, override templates and/or static files.\n\nRoot template is :\n`templates/drf_autodocs/index.html`\n\n\nFor additional parsers(if you want other structure than tree), inherit from\n\n `drf_autodocs.parser.BaseAPIParser`\n\n# Configuration/settings\n\nEndpoint names could use view names or url names, replacing '_' and '-' with ' ' and capitalizing output.\n\nDefault behavior is to use url names:\n\n`url(r'^books/(?P\u003cpk\u003e\\d+)/$', library_views.BookReadUpdateHandler.as_view(), name='book_read_update'),`\n\nwill result in:\n\n![url_name](http://joxi.ru/Q2K1WDh4yXnGrj.jpg)\n\nIf you want to use endpoint(view) names instead, do this in settings:\n\n`AUTODOCS_ENDPOINT_NAMES = \"view\"`\n\n\n\n# Supports\n  - Python 3\n  - Django 1.8+\n  - Django Rest Framework 3+\n\n\n# Credits\nThanks to [django](http://djangoproject.com), [django-REST](http://www.django-rest-framework.org/) for their awesome work,\nand [drf-docs](https://github.com/manosim/django-rest-framework-docs) for source of inspiration as well as some parts of code.\n\n\nDeveloped with care by Mashianov Oleksander at\n\n[![buddhasoft](http://i63.tinypic.com/2h87nzm.png)](http://buddhasoft.net/)\n\n\nIf you :thumbsup: this, don't forget to :star: it and share with friends.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FiMakedonsky%2Fdrf-autodocs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FiMakedonsky%2Fdrf-autodocs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FiMakedonsky%2Fdrf-autodocs/lists"}