Add basic schema_view and a default url that maps to it

[malikoth]

@marcgibbons, what would you think about adding a schema_view that does basically what the example shows directly to this package? I liked the old version, I see no reason to require the user to create a whole view just for Swagger (Or, OpenAPI). So I basically copied the example schema_view and added a route to it in urls.py, so that you can I can include Swagger the same way we used to:

urlpatterns += [
    url(r'^swagger/', include('rest_framework_swagger.urls')),
]

The one difficulty was the fact that in your example, the title for the SchemaGenerator was hard-coded. So I played around with it, and found that there are two places to include Swagger:

• Django App
• Django Project

Specified in App

In the first case, it's possible to programmatically get the name of the app, and then you could just insert that. Just remember to set your app_name in your urls.py by following one of the two examples shown here.

Extending the example above, this then would look like (in increasing order of my personal preference):

urlpatterns += [
    url(r'^swagger/', include((
        url(r'^$', include('rest_framework_swagger.urls'),
        'my-application'
    ))),
]

or

app_name = 'my-application'
urlpatterns += [
    url(r'^swagger/', include('rest_framework_swagger.urls')),
]

(I also considered replacing - and _ characters in the app_name with spaces to generate the api title, just in case. What do you think?)

Specified in Project

In the second case, I can't find anyplace that specifies a "name" of your Django project, so I just defaulted to grabbing the name of the Django project folder.

Title Set Explicitly

Alternatively, this schema_view implementation also accepts the title as an extra argument, as shown here.

urlpatterns += [
    url(r'^swagger/', include('rest_framework_swagger.urls'), {'title': 'My Application API'),
]

This method of finding a name for the schema seems OK for a first-go to me, but I'm not married to it. If you like this PR, I'd be happy to modify the documentation accordingly, but I'll wait for a thumbs-up before I go to that effort.

[codecov-io]

Current coverage is 60.60% (diff: 100%)

Merging #493 into master will decrease coverage by 24.50%

@@             master       #493   diff @@
==========================================
  Files             3          5     +2   
  Lines            47         66    +19   
  Methods           0          0          
  Messages          0          0          
  Branches          2          4     +2   
==========================================
  Hits             40         40          
- Misses            7         26    +19   
  Partials          0          0          

Powered by Codecov. Last update dc1eaec...7c22eb9

[marcgibbons]

Thanks for this! This is cool, but I am somewhat hesitant to introduce this just yet. Ideally, we'd want to provide all the flexibility of configuration the schema view; the kwargs for the schema generator, view permissions, whether or not to include the request object, etc. Since the schema generation is still very new and still being developed, my preference is to keep this loose for now.

Also, the schema view can originate from a Router (although needs a fix to make it a default) (encode/django-rest-framework#4268)

[malikoth]

Ah, well I guess this submission was a bit naive, then. :) Looking at the schema documentation in DRF, I only see three kwargs, which wouldn't so bad to support along with the optional request argument. I don't know much about view permissions, though.

It seems that it would be nice to have something like this in place even if schema generation isn't locked down, as a basis for future modification, but it's not that big of a deal to just include a copy of this view in my project anyways for now.

Is there anything I could do to make this PR useful to this project in any way? If not, feel free to just close the PR.

[marcgibbons]

@malikoth It is a good idea, and I think a nice convenience to get people quickly up and running. Things are still in flux, so I will keep it in the backlog and revisit. Thank you so much!