marcgibbons / django-rest-swagger Goto Github PK

Currently DRF only allows documentation at the class level, but it would be nice to take advantage of Swagger's ability to document at the method/action level (ie, so "GET /users", "GET /users/{id}/friends", and "DELETE /users" can all have separate documentation). Are there any plans for this? Would it be considered?

At the end of the rest-framework tutorial I decided to give django rest swagger a whirl.
For reference, I tried this on:

• Django v1.5.1
• Django-REST-framework v2.3.6

The installation instructions for django-rest-swagger were easy enough as per the ReadMe. However, when I tried to load it in the browser as served from the django dev server I got a whole bunch of 404 errors for some JavaScript libs that it couldn't load.

Opening up the <path to virtual env>/lib/python2.7/site-packages/rest_framework_swagger/static/rest_framework_swagger/ directory showed that the whole lib directory was missing. I created a lib directory as it was expecting and hunted around for all its files around the interwebs, creating them with the names it was expecting.

Reloading the page indicated it was much happier with this arrangement:

The page at http://localhost:8000/api-docs/ wouldn't still fully load, however, but it turned out that the swagger-ui.js file at line 1420 was looking for a apisArray property of the model object, which didn't exist. A quick look through the webkit debugger suggested it perhaps meant to look for the resourcesArray property, to which I changed it to and it worked.

Here's the snippet of the change I made to make it work:

    MainView.prototype.render = function() {
      var resource, _i, _len, _ref;
      $(this.el).html(Handlebars.templates.main(this.model));
      // _ref = this.model.apisArray;
      _ref = this.model.resourcesArray;
      for (_i = 0, _len = _ref.length; _i < _len; _i++) {
        resource = _ref[_i];
        this.addResource(resource);
      }
      return this;
    };

Not sure if I took some weird journey to all this and it wouldn't be an issue if I'd followed some different steps to set it up. If this is indeed an issue, however, and this is the solution, I hope it helps others going down the same path.
I think it'd be super sweet tacking on swagger as a final part of Tutorial6 as it follows on quite nicely.

Hi,

i don't understand why my help_text strings don't appear in the UI

here is my serializer

class CategorySerializer(serializers.ModelSerializer):
    name = serializers.Field(source='nome', help_text="Category name")
    url = serializers.Field(source='url', help_text="Category url (domain not included)")
    parent = serializers.SerializerMethodField('_padre')
    challenges = serializers.SerializerMethodField('get_notizie')

    def _padre(self, obj):
        serializer = CategorySerializer(instance=obj.padre, context=self.context)
        return serializer.data

    def get_notizie(self, obj):
        return obj.notizie.all().values_list('id', flat=True)

    class Meta:
        model = Settore
        fields = ('id', 'name', 'url', 'parent', 'challenges')

The result is without help_text labels

http://i.imgur.com/mR2pVAN.png

What am I missing?

Thanks

Alessandro

I updated the rest_framework_swagger and this error popped up,
(I have the latest djangorestframework).

/site-packages/rest_framework_swagger/docgenerator.py", line 7, in
from rest_framework.utils.formatting import get_view_name,
ImportError: cannot import name get_view_name

Also looked in rest_framework folder get_view_name and get_view_description is in views.py

so this worked for me..
(/site-packages/rest_framework_swagger/docgenerator.py)
from rest_framework.views import get_view_name, get_view_description

{
"detail": "CSRF Failed: CSRF token missing or incorrect."
}

In settings.py:

SWAGGER_SETTINGS = {
    "exclude_namespaces": [],
    "api_version": '1',
    "enabled_methods": [
        'get',
        'post',
        'put',
        'patch',
        'delete'
    ],
    "is_authenticated": False
}

However version is not picked:
{"basePath": "http://192.168.211.130:8080/swagger/api-docs", "swaggerVersion": "1.2", "apiVersion": "", "apis": [{"path": "/api/auth"}, {"path": "/api/v1"}]}

The apiVersion should be '1' and it is not.
This suggests that the SWAGGER_SETTINGS is not really being picked up by swagger.

Hi,

This may simply be my misunderstanding of the intended behavior, but I'm not getting the results I expect from the enabled_methods setting. I have included only "get" in this list, but my api docs include the "Try it out!" button for both POST and GET methods. I was hoping the point of this setting would be to allow me to show docs for the POST method, but not allow users to actually call that method from the docs. BIG disclaimer, I'm using django 1.4, which I know is unsupported, but it looks like a lot of this setting is implemented in javascript, so I don't know if that would matter so much.

Here's from my settings.py:

...
SWAGGER_SETTINGS = {
    "enabled_methods": [
        "get",
    ]
}
...

And here's what my docs look like:

Am I doing anything wrong, besides using the wrong django version? Or is there an issue here?

If I understood correctly, now it looks like this:

"""
param_name -- param description
"""

But how can I specify the type of param (int, char etc.)? And can I specify the response format from docstring?
Thanks for help

Hi,

i would like to customize comments shown in swagger for my viewsets for available actions.

Now i have a docstring on the Viewset

class ReplyViewSet(ReazioneViewSet):
    """ Replies are free comments to reasons """
    serializer_class = ReplySerializer

and the result is http://i.imgur.com/Q7CCfTo.png

I would like to be able to change GET description (for example).

I have successfully added personalized comments for custom action defined with @action decorator, obviously adding docstring for the method.

But for method inherited from mixins (like create, destroy, list etc), what is the best way to achieve this?

I've tried overriding the default method, adding the custom docstring and then calling super (like above)

    def create(self, request, *args, **kwargs):
        """ Custom comment """
        super(model.ViewSet, self).create(request, *args, **kwargs)

but i get an AssertionError from DRF

I think this screenshot explains it best. The fix is probably to just use boundary escapes in whatever regex matching is being done. I would submit a pull request but I'm not familiar with the testing framework and short on time.

My site forces all connections to be over HTTPS. For some reason, swagger is trying to load from HTTP (which is redirecting it to HTTPS) causing cross-origin errors (even though it is all on the same server).

It is deployed here:
https://www.muckrock.com/api_doc/

Is there a way to configure swagger to only use HTTPS?

https://github.com/marcgibbons/django-rest-swagger/blob/master/rest_framework_swagger/introspectors.py#L387

This construct is not available in Python until version 2.7, which means it can't be used on systems running RHEL 6.x (only at python 2.6.6).
Not sure if there's a conscious decision to target Python versions, but it seems like this is the only blocker to running on 2.6.

Instead, we can use:

mapping = dict((value,key) for key,value in self.METHOD_MAPPINGS.iteritems())

?

I installed required packages into my virtual env. However, when I reference this in INSTALLED_APPS I get this error:

ImportError: No module named rest_framework_swagger

When I run python manage.py runserver,and access to /doc in the browser, the error occurred.

TemplateDoesNotExist at /docs/
rest_framework_swagger/index.html

Example in the EventSeriealizer seems to have some logic problem.

def validate(self, attrs):
"""
Check that the start is before the stop.
"""
if attrs['start'] < attrs['finish']:
raise serializers.ValidationError("finish must occur after start") #????????
return attrs

Would patches adding Django 1.4 compatibility be considered? If so, I'll send some PRs.

Does django-rest-sweagger checks if append_slash has been disabled in settings.py?

I have append_slash=False
and in python2.7/site-packages/rest_framework_swagger/urls.py
I had to remove forward slash from line # 9 (to make it work)
url(r'^api-docs/(?P<path>.*)$', SwaggerApiView.as_view(), name='django.swagger.api.view'),

pip install --upgrade django-rest-swagger

updated my django! to Django-1.5.4

and now its throwing this error:

Traceback (most recent call last):
  File "./manage.py", line 8, in <module>
    from django.core.management import execute_from_command_line
ImportError: No module named core.management

any way to update only the software and not all the packages?
I want to keep my django to 1.5.1 (as say in requirements)

I have a view like:

class RegistrationView(APIView):
    """    
    Creates a new user.
    Returns: token - auth token.

    email -- e-mail address
    password -- password, optional
    city -- city, optional
    street -- street, optional
    number -- house number, optional
    zip_code -- zip code 10 chars, optional
    phone -- phone number in US format (XXX-XXX-XXXX), optional
    """

This is rendered as:

   Implementation Notes

   Creates a new user.
   Returns: token - auth to

   Parameters
   (...)

The problem is that the token word is shortened to to.

My API structure looks like:
/publications/
/publications//sections/
/publications//sections//articles/
etc.

However, Swagger groups all of these under /publications/

Is there a workaround/proposal to fix this?

It would be really useful to pull docstrings from the individual APIView methods, if available. For example, if you were to override the create method of a ListCreateAPIView and the custom create method has its own docstring, use that instead of the class' docstring.

This may not be useful...

Given the following snip of a view. Swagger Correctly shows the enable API as a valid URL and so on, but inherits all the docs/and options of the viewset class.

It would be awesome if one, it shows the doc of the method (this is already a documented issue) but also only shows the correct HTTP OPTIONS of said method.

from django.db import transaction
from rest_framework.decorators import action

class FooViewSet(CreateUpdateListRetrieveViewSet):
    """
    Get list of Foo objects.
    OPTIONS: GET, POST, PATCH
    """
    model = Foo
    lookup_field = 'name'

    @action()
    @transaction.commit_on_success
    def enable(self, request, *args, **kwargs):
        """
        enables a Foo object.

        """
        serializer = FooSerializer(self.get_object())
        return Response({'object': serializer.data}, status=200)

I'm using Django 1.6.2, django-rest-framework 2.3.12, and python 3.3.4

Running the cigar_example locally errors out when trying to view the swagger documentation at http://127.0.0.1:8000/. http://127.0.0.1:8000/api/cigars/ loads properly (when including trailing slash) and the remainder of the documentation loads properly if I remove the cigars route in cigar_example/restapi/urls.py.

The documentation page gives the error - Unable to read api 'cigars' from path http://127.0.0.1:8000/api-docs/api/cigars (server returned undefined)
The stack trace is below.
[08/Mar/2014 11:59:59] "GET /api-docs/ HTTP/1.1" 200 215
Internal Server Error: /api-docs/api/cigars
Traceback (most recent call last):
File "D:\Development\virtualenv\aws-django\lib\site-packages\django\core\handlers\base.py", line 114, in get_response
response = wrapped_callback(request, _callback_args, *_callback_kwargs)
File "D:\Development\virtualenv\aws-django\lib\site-packages\django\views\generic\base.py", line 69, in view
return self.dispatch(request, _args, *_kwargs)
File "D:\Development\virtualenv\aws-django\lib\site-packages\django\views\decorators\csrf.py", line 57, in wrapped_view
return view_func(_args, *_kwargs)
File "D:\Development\virtualenv\aws-django\lib\site-packages\rest_framework\views.py", line 399, in dispatch
response = self.handle_exception(exc)
File "D:\Development\virtualenv\aws-django\lib\site-packages\rest_framework\views.py", line 396, in dispatch
response = handler(request, _args, *_kwargs)
File "D:\Development\virtualenv\aws-django\lib\site-packages\rest_framework_swagger\views.py", line 84, in get
'apis': generator.generate(apis),
File "D:\Development\virtualenv\aws-django\lib\site-packages\rest_framework_swagger\docgenerator.py", line 21, in generate
'operations': self.get_operations(api),
File "D:\Development\virtualenv\aws-django\lib\site-packages\rest_framework_swagger\docgenerator.py", line 41, in get_operations
for method_introspector in introspector:
File "D:\Development\virtualenv\aws-django\lib\site-packages\rest_framework_swagger\introspectors.py", line 285, in iter
methods = self._resolve_methods()
File "D:\Development\virtualenv\aws-django\lib\site-packages\rest_framework_swagger\introspectors.py", line 294, in _resolve_methods
raise RuntimeError('Unable to use callback invalid closure/function specified.')
RuntimeError: Unable to use callback invalid closure/function specified.
[08/Mar/2014 11:59:59] "GET /api-docs/api/manufacturers HTTP/1.1" 200 3514
[08/Mar/2014 11:59:59] "GET /api-docs/api/custom HTTP/1.1" 200 931
[08/Mar/2014 11:59:59] "GET /api-docs/api/countries HTTP/1.1" 200 2694
[08/Mar/2014 12:00:00] "GET /api-docs/api/cigars HTTP/1.1" 500 122324

How can I show models schema in django-rest-swagger?

something like:
""" This is the model """

Also, do you have any style guide or perhaps link to django-rest-framework-docs style-guide, where I can find all the available features with example.

Thank you

Hello guys,

I have a problem setting up the app. To preface the description of the problem, my django version is 1.5.1 and django rest framework is 2.3.7, django-rest-swagger is 0.1.7.

Basically I have done what the README says (i.e. put the app in INSTALLED_APPS and configured the urls with the default api-docs/.

After all this has been done though, when I go to localhost:8000/api-docs I see the Swagger page, but it tries to load my apps and fails with a message like

Unable to read api 'animals' from path http://localhost:8000/api-docs/api-docs/animals (server returned NOT FOUND).

I tried to search for "Unable to read" in the source code, but it strangely returned nothing so I do not even know where this is coming from. The jQuery being unreadable does not help either. Basically what I am trying to understand is why the rest swagger is looking for my app 'animals' in /api-docs/api-docs/ (the app is accessible through /animals).

I would appreciate it if you help, if you need more info, just ask.

I set up django-rest-swagger as specified in the README. When I navigate to my api root in the django-rest-swagger interface, I get a loading prompt saying fetching resource list: http://localhost:8000/rs/ that remains indefinitely.

I have not been able to get it to work, so I have to revert to django-rest-docs for now.

Any idea why this might be happening?

Current version of rest-framework-swagger doesn't allow defining parameters in more than one line, only the first line is displayed.

For example consider this line:

store_id -- (optional) store number to which restrict the
search. If this parameter is provided then the available inventory
for each product will be included in the response.

The current code is splitting the lines and taking only the first one, as it contains "--". Problem is in introspectors.py:L253.

I can create a patch for this issue so the whole paragraph of the parameter description is used, removing endlines appropiately.

I love django-rest-swagger.
I have a custom json render and parser for camel case field
https://gist.github.com/johtso/5881137

and
settings
'DEFAULT_RENDERER_CLASSES': (
'utils.api.renderers.CamelCaseJSONRenderer',
'rest_framework.renderers.BrowsableAPIRenderer',
),

django-rest-swagger not work, I hope be add a settings for choose default json render or custom

Hi, I'm having an issue testing a POST request because the server expects a plain JSON object in raw post data.

Is there any support for this kind of usage?

Here's an example of an interface that could be generated:
http://lbovet.github.io/swagger-ui/dist/index.html#!/test/putInvoice_put_1

Thank you

First of all, thanks for this great work !

Can't remember the exact version of django-rest-framework that introduced routers and viewsets but for my api that uses those features the doc is empty.

Will try to work on a pull request when I've finished and polished my api.

Cheers

I'm not sure if django-rest-swagger is compatible with 3.6, but I have an issue with my DjangoModelPermissions when I use this small framework.

I think it goes wrong in the APIDocView class which extends the APIView class. According to this post (http://stackoverflow.com/a/17166441/1149127) on stackoverflow from Tom Christie (June 18) a class based view needs a model to determine the model permissions for the view. Looking at APIDocView (and the inheritance in SwaggerResourcesView) it hasn't a queryset or model variable set. https://github.com/marcgibbons/django-rest-swagger/blob/master/rest_framework_swagger/apidocview.py < APIDocView

Maybe that's why I get this AssertionError when I try to call the documentation via /api/api-docs/. Full error:

Cannot apply DjangoModelPermissions on a view that does not have .model or .queryset property.

Does anyone know how to solve this permission model problem in a correct way?

django-rest-swagger tries to import settings on installation and fails if the setting file isn't in the path.

$ pip install django-rest-swagger
Downloading/unpacking django-rest-swagger
  Running setup.py egg_info for package django-rest-swagger
    Traceback (most recent call last):
      File "<string>", line 16, in <module>
      File "[VIRTUALENV_PATH]/build/django-rest-swagger/setup.py", line 3, in <module>
        from rest_framework_swagger import VERSION
      File "rest_framework_swagger/__init__.py", line 14, in <module>
        SWAGGER_SETTINGS = getattr(settings, 'SWAGGER_SETTINGS', DEFAULT_SWAGGER_SETTINGS)
      File "[VIRTUALENV_PATH]/lib/python2.7/site-packages/django/conf/__init__.py", line 53, in __getattr__
        self._setup(name)
      File "[VIRTUALENV_PATH]/lib/python2.7/site-packages/django/conf/__init__.py", line 48, in _setup
        self._wrapped = Settings(settings_module)
      File "[VIRTUALENV_PATH]/lib/python2.7/site-packages/django/conf/__init__.py", line 134, in __init__
        raise ImportError("Could not import settings '%s' (Is it on sys.path?): %s" % (self.SETTINGS_MODULE, e))
    ImportError: Could not import settings 'settings' (Is it on sys.path?): No module named settings
    Complete output from command python setup.py egg_info:
    Traceback (most recent call last):

  File "<string>", line 16, in <module>

  File "[VIRTUALENV_PATH]/build/django-rest-swagger/setup.py", line 3, in <module>

    from rest_framework_swagger import VERSION

  File "rest_framework_swagger/__init__.py", line 14, in <module>

    SWAGGER_SETTINGS = getattr(settings, 'SWAGGER_SETTINGS', DEFAULT_SWAGGER_SETTINGS)

  File "[VIRTUALENV_PATH]/lib/python2.7/site-packages/django/conf/__init__.py", line 53, in __getattr__

    self._setup(name)

  File "[VIRTUALENV_PATH]/lib/python2.7/site-packages/django/conf/__init__.py", line 48, in _setup

    self._wrapped = Settings(settings_module)

  File "[VIRTUALENV_PATH]/lib/python2.7/site-packages/django/conf/__init__.py", line 134, in __init__

    raise ImportError("Could not import settings '%s' (Is it on sys.path?): %s" % (self.SETTINGS_MODULE, e))

ImportError: Could not import settings 'settings' (Is it on sys.path?): No module named settings

Workaround: add the path where the project resides to the PYTHONPATH.

Hi,

My first question is can I specify custom parameters and custom serializers for each ModelViewSet methods.
My second question is can I specify parameter types for this custom parameters?

For example:

class ReviewViewSet(viewsets.ModelViewSet):
    """ Review endpoint to list, create, display, delete, like, dislike and
    report a review or list likes, dislikes and reports tied to a review.

    To receive the response as JSON, add the format parameter.
    Example: /api/v1/review/?format=json
    """
    serializer_class = ReviewSerializer
    queryset = Review.objects.all()

    def list(self, request):
        """
        Lists the all reviews by paginating.

       param1 -- first parameter
       param2 -- second parameter
        """
        return super(ReviewViewSet, self).list(request)

    def retrieve(self, request, pk=None):
        """
        Displays the requested review.

        param3 -- third parameter
        """
        return super(ReviewViewSet, self).retrieve(request, pk=pk)

    @action(permission_classes=[IsAuthenticated])
    def like(self, request, pk=None):
        """
        Likes a review. User authentication is required.

        # I want no params for this action and I want to show a different serializer class.
        """
        review = self.get_object()
        try:
            review.like(request.user.userprofile)
            return Response({}, status=status.HTTP_200_OK)
        except ReviewLikeExistException, e:
            return Response({'message': e.message},
                            status=status.HTTP_400_BAD_REQUEST)

Until this Unipath issue [1] is resolved Rest Swagger doesn't work on Python3.

[1] mikeorr/Unipath#4

It does not seem to work with e.g. django-storages.

In my team, We speak chinese. So, I must write chinese comment.
When i write comment in view's functions.(list, create, destroy ...)
I Got
UnicodeDecodeError: 'ascii' codec can't decode byte 0xe7 in position 22: ordinal not in range(128)

Steps to reproduce:

1. Django + swagger + Python 2

2. Put into settings.py:

   SWAGGER_SETTINGS = {"enabled_methods": [u"get"]}
   

3. View swagger docs in browser

Expected result: GET based api calls are documented.

Actual result: Blank page.

There is a javascript error "Uncaught SyntaxError: Unexpected string ". Looking at the source we see:

supportedSubmitMethods: [u'get'],

And the problem becomes clear - we are relying on python repr() to output the methods to javascript, but this is producing Python syntax for unicode strings. The solution is to json encode the enabled methods instead of simply dumping them.

This is a non-academic problem for anyone who defines

from __future__ import unicode_literals

Is anybody already working on the transition to Swagger 1.2?

In our implementation of rest_framework, in two examples we extend the get_serializer_class method. Example:

def get_serializer_class(self):
    self.serializer_class.context = {'request': self.request}
    return self.serializer_class

(The serializer class behaves differently based on request parameters.)

This results in an error:

File "/Library/Python/2.7/site-packages/rest_framework_swagger/docgenerator.py", line 336, in get_serializer_class
return callback().get_serializer_class()
File "/path/to/working/app/views.py", line 52, in get_serializer_class
if self.request.method == "GET":
AttributeError: 'AppListView' object has no attribute 'request'

I have this url on urls.py:
url(
regex=r'^auth/signup/$',
view=UserCreateView.as_view(),
name ='auth-signup'
),
but swagger displays a resource called 'uth' insted of 'auth'. Also if I click it don't expands the list of REST calls.

Such as 'exclude_namespaces': ['/users/'] not work
Is there some example?
Thank you.

Parse permission classes set for API Views and include to the implementation notes

It's not entirely uncommon for a contextprocessor to add a settings object to the context. This settings naturally reflects the django settings. If such a context processor is enabled it overwrites the settings object used to pass swagger settings to the template.

Since swagger is breaking convention here, it probably is the thing that should change.

The question is, how much will it break backwards compatibility?

So there would be two suggestions:

• change the context variable to swagger_settings
• access the settings from settings.SWAGGER_SETTINGS.enabled_methods|safe etc.

Thoughts?

HI,
Sorry to create a separate issue for this but I can really use some help on this one.

Wondering how django-rest-swagger display "Response Class", "Response Content Type", and "Error Status Codes"?

Is there a specific way to comment it or do I need to use something in django-rest-framework?

I can see all the api end-points in django-rest-swagger but not the above details.
Thank you.

Hey Marc,

I've tried the django-rest-swagger with our current production ready API. We're running Django 1.4.3 and djangorestframework 2.3.7. I've followed the steps in your README, but only certain views/methods are appearing in the swagger explorer. When the method is declared like this:

url(r'^user-(?P<user_id>[a-zA-Z0-9]+)/carts$', cart.CartsListCreateView.as_view() ),

(note: we use hyphen-style for REST resource declaration)

rest-swagger is not declaring it. Other methods declared like this:

url(r'^rooms/room-(?P[a-zA-Z0-9-]+)$', room.RoomView.as_view() ),

are properly inspected and appear in the api-docs auto generated html file.

Any idea?

Hi,

how can I exclude POST updates to my resources?

When i expose a resource for POST method, i get two endpoints:

POST /api/resources
POST /api/resources/{pk}

how can i avoid to list the second one?

A concrete example:

http://i.imgur.com/KQPEsAF.png

I use a simple viewset with zero custom definitions

class ReasonViewSet(models.ViewSet):
    """ [comment] """
    serializer_class = ReasonSerializer