Add swagger_auto_schema method decorator for Operation customization

See #5.

tests/conftest.py

@@ -1,3 +1,6 @@
+import json
+import os
+
 import pytest
 from ruamel import yaml
 
@@ -53,3 +56,9 @@ def bad_settings():
     SWAGGER_DEFAULTS['SECURITY_DEFINITIONS'].update(bad_security)
     yield swagger_settings
     del SWAGGER_DEFAULTS['SECURITY_DEFINITIONS']['bad']
+
+
+@pytest.fixture
+def reference_schema():
+    with open(os.path.join(os.path.dirname(__file__), 'reference.json')) as reference:
+        return json.load(reference)

tests/reference.json

@@ -0,0 +1 @@
+{"swagger": "2.0", "info": {"title": "Snippets API", "description": "Test description", "termsOfService": "https://www.google.com/policies/terms/", "contact": {"email": "contact@snippets.local"}, "license": {"name": "BSD License"}, "version": "v1"}, "paths": {"/articles/": {"get": {"operationId": "articles_list", "description": "ArticleViewSet class docstring", "parameters": [{"name": "title", "in": "query", "description": "", "required": false, "type": "string"}, {"name": "limit", "in": "query", "description": "Number of results to return per page.", "required": false, "type": "integer"}, {"name": "offset", "in": "query", "description": "The initial index from which to return the results.", "required": false, "type": "integer"}], "responses": {"200": {"description": ""}}, "consumes": ["application/json"], "tags": ["articles"]}, "post": {"operationId": "articles_create", "description": "ArticleViewSet class docstring", "parameters": [{"name": "data", "in": "body", "schema": {"type": "object", "properties": {"title": {"description": "title model help_text", "type": "string"}, "body": {"description": "body serializer help_text", "type": "string"}, "slug": {"description": "slug model help_text", "type": "string", "format": "slug"}, "date_created": {"type": "string", "format": "date-time"}, "date_modified": {"type": "string", "format": "date-time"}}}}, {"name": "limit", "in": "query", "description": "Number of results to return per page.", "required": false, "type": "integer"}, {"name": "offset", "in": "query", "description": "The initial index from which to return the results.", "required": false, "type": "integer"}], "responses": {"201": {"description": ""}}, "consumes": ["application/json"], "tags": ["articles"]}, "parameters": []}, "/articles/today/": {"get": {"operationId": "articles_today", "description": "ArticleViewSet class docstring", "parameters": [{"name": "title", "in": "query", "description": "", "required": false, "type": "string"}, {"name": "limit", "in": "query", "description": "Number of results to return per page.", "required": false, "type": "integer"}, {"name": "offset", "in": "query", "description": "The initial index from which to return the results.", "required": false, "type": "integer"}], "responses": {"200": {"description": ""}}, "consumes": ["application/json"], "tags": ["articles"]}, "parameters": []}, "/articles/{slug}/": {"get": {"operationId": "articles_read", "description": "retrieve class docstring", "parameters": [], "responses": {"200": {"description": ""}}, "consumes": ["application/json"], "tags": ["articles"]}, "put": {"operationId": "articles_update", "description": "update method docstring", "parameters": [{"name": "data", "in": "body", "schema": {"type": "object", "properties": {"title": {"description": "title model help_text", "type": "string"}, "body": {"description": "body serializer help_text", "type": "string"}, "slug": {"description": "slug model help_text", "type": "string", "format": "slug"}, "date_created": {"type": "string", "format": "date-time"}, "date_modified": {"type": "string", "format": "date-time"}}}}], "responses": {"200": {"description": ""}}, "consumes": ["application/json"], "tags": ["articles"]}, "delete": {"operationId": "articles_delete", "description": "destroy method docstring", "parameters": [], "responses": {"204": {"description": ""}}, "consumes": ["application/json"], "tags": ["articles"]}, "patch": {"operationId": "articles_partial_update", "description": "partial_update description override", "parameters": [{"name": "data", "in": "body", "schema": {"type": "object", "properties": {"title": {"description": "title model help_text", "type": "string"}, "body": {"description": "body serializer help_text", "type": "string"}, "slug": {"description": "slug model help_text", "type": "string", "format": "slug"}, "date_created": {"type": "string", "format": "date-time"}, "date_modified": {"type": "string", "format": "date-time"}}}}], "responses": {"200": {"description": ""}}, "consumes": ["application/json"], "tags": ["articles"]}, "parameters": [{"name": "slug", "in": "path", "description": "slug model help_text", "required": true, "type": "string"}]}, "/articles/{slug}/image/": {"get": {"operationId": "articles_image_read", "description": "image GET description override", "parameters": [], "responses": {"200": {"description": ""}}, "consumes": ["multipart/form-data"], "tags": ["articles"]}, "post": {"operationId": "articles_image_create", "description": "image method docstring", "parameters": [{"name": "upload", "in": "formData", "description": "image serializer help_text", "type": "file"}], "responses": {"201": {"description": ""}}, "consumes": ["multipart/form-data"], "tags": ["articles"]}, "parameters": [{"name": "slug", "in": "path", "description": "slug model help_text", "required": true, "type": "string"}]}, "/snippets/": {"get": {"operationId": "snippets_list", "description": "SnippetList classdoc", "parameters": [], "responses": {"200": Line truncated

tests/test_api_view.py

@@ -1,6 +1,17 @@
+from drf_swagger import openapi
+
+
 def test_operation_docstrings(swagger_dict):
     users_list = swagger_dict['paths']['/users/']
     assert users_list['get']['description'] == "UserList cbv classdoc"
+    assert users_list['post']['description'] == "apiview post description override"
 
     users_detail = swagger_dict['paths']['/users/{id}/']
     assert users_detail['get']['description'] == "user_detail fbv docstring"
+    assert users_detail['put']['description'] == "user_detail fbv docstring"
+
+
+def test_parameter_docstrings(swagger_dict):
+    users_detail = swagger_dict['paths']['/users/{id}/']
+    assert users_detail['get']['parameters'][0]['description'] == "test manual param"
+    assert users_detail['put']['parameters'][0]['in'] == openapi.IN_BODY

tests/test_generic_viewset.py

@@ -18,12 +18,12 @@ def test_operation_docstrings(swagger_dict):
     articles_detail = swagger_dict['paths']['/articles/{slug}/']
     assert articles_detail['get']['description'] == "retrieve class docstring"
     assert articles_detail['put']['description'] == "update method docstring"
-    assert articles_detail['patch']['description'] == "ArticleViewSet class docstring"
+    assert articles_detail['patch']['description'] == "partial_update description override"
     assert articles_detail['delete']['description'] == "destroy method docstring"
 
     articles_today = swagger_dict['paths']['/articles/today/']
     assert articles_today['get']['description'] == "ArticleViewSet class docstring"
 
     articles_image = swagger_dict['paths']['/articles/{slug}/image/']
-    assert articles_image['get']['description'] == "image method docstring"
+    assert articles_image['get']['description'] == "image GET description override"
     assert articles_image['post']['description'] == "image method docstring"

tests/test_reference_schema.py

@@ -0,0 +1,2 @@
+def test_reference_schema(swagger_dict, reference_schema):
+    return swagger_dict == reference_schema