Makes it possible to ignore user permissions when generating a schema.

I have an endpoint which lists search results (/v1/search_results/), but I'm only given access if I specify a search ID on the query string (/v1/search_results/?search=456). My code checks that the logged in user owns search 456 before allowing the user to access this endpoint.

Without this setting, /v1/search_results/ won't appear in the generated documentation.

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

This parser allows you override some parts of automatic method inspection behaviours which are not always correct. Also you may style your documentation with Markdown syntax.

Docstring parser powered by YAML syntax

This parser allows you override some parts of automatic method inspection
behaviours which are not always correct.

See the following documents for more information about YAML and Swagger:
- https://github.com/wordnik/swagger-core/wiki
- http://www.yaml.org/spec/1.2/spec.html
- https://github.com/wordnik/swagger-codegen/wiki/Creating-Swagger-JSON-from-YAML-files

1. Control over parameters
============================================================================
Define parameters and its properties in docstrings:

    parameters:
        - name: some_param
          description: Foobar long description goes here
          required: true
          type: integer
          paramType: form
          minimum: 10
          maximum: 100
        - name: other_foo
          paramType: query
        - name: avatar
          type: file

It is possible to override parameters discovered by method inspector by
defining:
    `parameters_strategy` option to either `merge` or `replace`

To define different strategies for different `paramType`'s use the
following syntax:
    parameters_strategy:
        form: replace
        query: merge

By default strategy is set to `merge`


Sometimes method inspector produces wrong list of parameters that
you might not won't to see in SWAGGER form. To handle this situation
define `paramTypes` that should be omitted
    omit_parameters:
        - form

2. Control over serializers
============================================================================
Once in a while you are using different serializers inside methods
but automatic method inspector cannot detect this. For that purpose there
is two explicit parameters that allows you to discard serializer detected
by method inspector OR replace it with another one

    serializer: some.package.FooSerializer
    omit_serializer: true

3. Custom Response Class
============================================================================
If your view is not using serializer at all but instead outputs simple
data type such as JSON you may define custom response object in method
signature like follows:

    type:
      name:
        required: true
        type: string
      url:
        required: false
        type: url

4. Response Messages (Error Codes)
============================================================================
If you'd like to share common response errors that your APIView might throw
you can define them in docstring using following format:

responseMessages:
    - code: 401
      message: Not authenticated
    - code: 403
      message: Insufficient rights to call this procedure


5. Different models for reading and writing operations
============================================================================
Since REST Framework won't output write_only fields in responses as well as
does not require read_only fields to be provided it is worth to
automatically register 2 separate models for reading and writing operations.

Discovered serializer will be registered with `Write` or `Read` prefix.
Response Class will be automatically adjusted if serializer class was
detected by method inspector.

You can also refer to this models in your parameters:

parameters:
    - name: CigarSerializer
      type: WriteCigarSerializer
      paramType: body


SAMPLE DOCSTRING:
============================================================================

---
# API Docs
# Note: YAML always starts with `---`

type:
  name:
    required: true
    type: string
  url:
    required: false
    type: url
  created_at:
    required: true
    type: string
    format: date-time

serializer: .serializers.FooSerializer
omit_serializer: false

parameters_strategy: merge
omit_parameters:
    - path
parameters:
    - name: name
      description: Foobar long description goes here
      required: true
      type: string
      paramType: form
    - name: other_foo
      paramType: query
    - name: other_bar
      paramType: query
    - name: avatar
      type: file

responseMessages:
    - code: 401
      message: Not authenticated

I've also added URL grouping and Token authentication from other PR's (credits goes there).

As far as I understand, the way to include the TokenAuthentication is use the SECURITY_DEFINITIONS settings.

In the OpenAPI Docs, in the "api_key" type, there are 3 keys: "type", "name", "in".

I guess that "in" should be "header", name "Authorization" and type should be left "apiKey". Where should I put the value "Token MYTOKEN"?

This ticket may be related to #497 , but I'm not sure.

Thanks in advance

I am using django-rest-swagger for api doc generation. I would like to return different user the different part of models. So I used the get_serializer_class() function to use different serializer for different users by checking the kwargs['pk'] on the url.

The urls.py is:

url(r'^api/users/$', views.UserEnum.as_view()),
url(r'^api/users/(?P<pk>[0-9]+)/$', views.UserDetail.as_view()),

The view that I am using is:

#List all the users or create a new user
class UserEnum(generics.ListCreateAPIView):
    queryset = User.objects.all()
    serializer_class = UserSerializer
    permission_classes = (IsAuthenticated, IsAdminUser,)

class UserDetail(generics.RetrieveUpdateDestroyAPIView):
    queryset = User.objects.all()
    #serializer_class = UserSerializer #TODO: Problem with Swagger
    permission_classes = (IsAuthenticated, IsOwnerAdminOrReadOnly,)

    def get_serializer_class(self):
        #swagger crash here.
        user_id = int(self.kwargs['pk'])
        if self.request.user.id == user_id or self.request.user.is_superuser:
            serializer_class = UserSerializer
        else:
            serializer_class = UserProfileSerializer
        return serializer_class

    def get_object(self, *args, **kwargs):
        user_id = int(self.kwargs['pk'])

        if self.request.user.id == user_id or self.request.user.is_superuser:
            return User.objects.get(id=user_id)
        else:
            return UserProfile.objects.get(user=user_id)

The above two urls work successfully without problems. But when I type the http://127.0.0.1:8000/api/ for generate api docs, it return the below error:

`Unable to read api 'users' from path http://127.0.0.1:8000/api/api-docs/api/users (server returned Internal Server Error)`


File "/Users/Scofield/anaconda/lib/python2.7/site-packages/rest_framework_swagger/introspectors.py" in ask_for_serializer_class
  179.                 return view.get_serializer_class()
File "/Users/Scofield/Dropbox/My Projects/Angels&Demons/src/doWishSites/doWishCore/views.py" in get_serializer_class
  27.         user_id = int(self.kwargs['pk'])

Exception Type: KeyError at /api/api-docs/api/users
Exception Value: 'pk'

I have PhotosViewSet with list and list_route upload action. I would like it to see under same 'photos' group in the docs.

What i am doing wrong? Is it supported?

for method in self.get_allowed_methods(callback):
    key = self.get_key(path, method, callback)

in SchemaGenerator get_key seems to not take 'list route' actions into account.

It looks like the version of swagger-api/swagger-ui that is in use by django-rest-swagger is quite old. From what I can see it looks like it's based on 2.0.17. Is there a reason it hasn't been updated? Would a PR updating to the latest be likely to be accepted? I see there have been a few changes made manually to the JS and CSS, but those changes could probably be re-applied if necessary.

I recently upgraded from 0.3.5 to 2.0.4. Previously, docstrings on view methods (MyView.get) would be included in the swagger generated docs, but with the new version I don't get any docs included. It does seem to introspect serializer fields and such, but the docstrings help users of the API understand what an endpoint does and when to use it. Is there any way to get those included with the current release?

• Current versions installed in my app:

django-rest-swagger==2.0.1 djangorestframework==3.4.0

• Brief configuration:

-- urls.py --

router = DefaultRouter()
router.register(r'documents', DocumentViewSet)
router.register(r'bounces', BounceViewSet)
router.register(r'users', UserViewSet)

#DOC SWAGGER API
url(r'^documentacion/$', esquema_doc_api),

-- views.py --

@api_view()
@renderer_classes([SwaggerUIRenderer, OpenAPIRenderer])
def esquema_doc_api(request):
    generator = schemas.SchemaGenerator(title='TEST API')
    return response.Response(generator.get_schema(request=request))

-- development server petitions log -- [19/Jul/2016 09:36:00] "GET /documentacion/?format=openapi HTTP/1.1" 500 83970

Now if I launch my project and type http://ip:port/documentacion/ in my browser I get an HTTP error 500 and display raw HTML content inside my Swagger view. The problem disappears when I use a logged in user. Anyway when l use a logged in user I still can see and endpoint with the same name that my scheme creator function 'esquema_doc_api' and returns HTML when I fire the GET method on it. I'm not pretty sure if it's supposed to be the standard behaviour.

I'll attach some screenshot with the problem.

Regards,

Javier Civantos

• Handles a particular class of decorated view functions that refer to the outermost closure arguments.
• Searches for a types.FunctionType argument in the closure, rather than assuming the first argument is the view. This is a correct implementation for existing cases as well.

The following documentation raised the error.

"""
    ---
    serializer: MySerializer
"""

Had to change docgenerator.py:42 from:

        if str(callback) == \
                "<class 'rest_framework.decorators.WrappedAPIView'>":

to

        if str(callback).startswith("<class 'rest_framework.decorators."):

This also reproduces for the example project and doesn't seem to be tested.

{% load staticfiles %} and {% load admin_static %} were deprecated in Django 2.1, and removed in Django 3.0. I propose to change it with {% load static %}

My main usage of the swagger docs is to try things with the API. It would be nice if we could disable the "Try it out" button and just have the form enabled by default so you save some pointing and clicking before you can try out a request. Or multiple requests.

The index.html file in the templates folder contains a load "staticfiles" import which I assume is for using the static tag.

However, this returns an error since this isn't the load command django recommends for static files. Hence, I changed:

{% load staticfiles %}

to

{% load static %}.

After this, it no longer throws the error of not recognizing the load staticfiles import.