Debian Codegraph @

tests/test_schema_generator.py

raw
1 import json
2 import sys
3 import typing
4
5 import pytest
6 from django.contrib.postgres import fields as postgres_fields
7 from django.db import models
8 from django.urls import path
9 from django.utils.inspect import get_func_args
10 from django_fake_model import models as fake_models
11 from rest_framework import routers, serializers, viewsets
12 from rest_framework.decorators import api_view
13 from rest_framework.response import Response
14
15 from drf_yasg import codecs, openapi
16 from drf_yasg.codecs import yaml_load
17 from drf_yasg.errors import SwaggerGenerationError
18 from drf_yasg.generators import OpenAPISchemaGenerator
19 from drf_yasg.utils import swagger_auto_schema
20
21
22 def test_schema_is_valid(swagger, codec_yaml):
23 codec_yaml.encode(swagger)
24
25
26 def test_invalid_schema_fails(codec_json, mock_schema_request):
27 # noinspection PyTypeChecker
28 bad_generator = OpenAPISchemaGenerator(
29 info=openapi.Info(
30 title="Test generator",
31 default_version="v1",
32 contact=openapi.Contact(name=69, email=[]),
33 ),
34 version="v2",
35 )
36
37 swagger = bad_generator.get_schema(mock_schema_request, public=True)
38 with pytest.raises(codecs.SwaggerValidationError):
39 codec_json.encode(swagger)
40
41
42 def test_json_codec_roundtrip(codec_json, swagger, validate_schema):
43 validate_schema(json.loads(codec_json.encode(swagger)))
44
45
46 def test_yaml_codec_roundtrip(codec_yaml, swagger, validate_schema):
47 yaml_bytes = codec_yaml.encode(swagger)
48 assert b"omap" not in yaml_bytes # ensure no ugly !!omap is outputted
49 assert (
50 b"&id" not in yaml_bytes and b"*id" not in yaml_bytes
51 ) # ensure no YAML references are generated
52 validate_schema(yaml_load(yaml_bytes))
53
54
55 def test_yaml_and_json_match(codec_yaml, codec_json, swagger):
56 yaml_schema = yaml_load(codec_yaml.encode(swagger))
57 json_schema = json.loads(codec_json.encode(swagger))
58 assert yaml_schema == json_schema
59
60
61 def test_basepath_only(mock_schema_request):
62 with pytest.raises(SwaggerGenerationError):
63 generator = OpenAPISchemaGenerator(
64 info=openapi.Info(title="Test generator", default_version="v1"),
65 version="v2",
66 url="/basepath/",
67 )
68
69 generator.get_schema(mock_schema_request, public=True)
70
71
72 def test_no_netloc(mock_schema_request):
73 generator = OpenAPISchemaGenerator(
74 info=openapi.Info(title="Test generator", default_version="v1"),
75 version="v2",
76 url="",
77 )
78
79 swagger = generator.get_schema(mock_schema_request, public=True)
80 assert "host" not in swagger and "schemes" not in swagger
81 assert swagger["info"]["version"] == "v2"
82
83
84 def test_security_requirements(swagger_settings, mock_schema_request):
85 generator = OpenAPISchemaGenerator(
86 info=openapi.Info(title="Test generator", default_version="v1"),
87 version="v2",
88 url="",
89 )
90 swagger_settings["SECURITY_REQUIREMENTS"] = []
91
92 swagger = generator.get_schema(mock_schema_request, public=True)
93 assert swagger["security"] == []
94
95 swagger_settings["SECURITY_REQUIREMENTS"] = None
96 swagger_settings["SECURITY_DEFINITIONS"] = None
97
98 swagger = generator.get_schema(mock_schema_request, public=True)
99 assert "security" not in swagger
100
101
102 def test_default_url(swagger_settings, mock_schema_request):
103 swagger_settings["DEFAULT_API_URL"] = "http://api.example.com"
104 generator = OpenAPISchemaGenerator(
105 info=openapi.Info(title="Test generator", default_version="v1"),
106 version="v2",
107 )
108
109 swagger = generator.get_schema(public=True)
110 assert swagger["host"] == "api.example.com"
111 assert swagger["basePath"] == "/"
112
113
114 def _basename_or_base_name(basename):
115 # freaking DRF... TODO: remove when dropping support for DRF 3.8
116 if "basename" in get_func_args(routers.BaseRouter.register):
117 return {"basename": basename}
118 else:
119 return {"base_name": basename}
120
121
122 @pytest.mark.parametrize(
123 "key,value,override_schema_key",
124 (
125 ("consumes", ["application/vnd.x-override"], None),
126 ("deprecated", True, None),
127 ("operation_description", "description override", "description"),
128 ("operation_id", "id override", "operationId"),
129 ("operation_summary", "summary override", "summary"),
130 ("produces", ["application/vnd.x-override"], None),
131 ("tags", ["tag override"], None),
132 ),
133 )
134 def test_overrides(key, value, override_schema_key):
135 @swagger_auto_schema(method="get", **{key: value})
136 @api_view()
137 def test_override(request, pk=None):
138 return Response({"message": "Hello, world!"})
139
140 generator = OpenAPISchemaGenerator(
141 info=openapi.Info(title="Test generator", default_version="v1"),
142 version="v2",
143 url="",
144 patterns=[path("test/", test_override)],
145 )
146
147 assert generator.get_schema(None, True)["paths"]["/test/"]["get"] == {
148 "description": "",
149 "operationId": "test_list",
150 "parameters": [],
151 "responses": openapi.Responses({200: openapi.Response("")}),
152 "tags": ["test"],
153 (key if override_schema_key is None else override_schema_key): value,
154 }
155
156
157 def test_replaced_serializer():
158 class DetailSerializer(serializers.Serializer):
159 detail = serializers.CharField()
160
161 class DetailViewSet(viewsets.ViewSet):
162 serializer_class = DetailSerializer
163
164 @swagger_auto_schema(
165 responses={
166 404: openapi.Response("Not found or Not accessible", DetailSerializer)
167 }
168 )
169 def retrieve(self, request, pk=None):
170 serializer = DetailSerializer({"detail": None})
171 return Response(serializer.data)
172
173 router = routers.DefaultRouter()
174 router.register(r"details", DetailViewSet, **_basename_or_base_name("details"))
175
176 generator = OpenAPISchemaGenerator(
177 info=openapi.Info(title="Test generator", default_version="v1"),
178 version="v2",
179 url="",
180 patterns=router.urls,
181 )
182
183 for _ in range(3):
184 swagger = generator.get_schema(public=True)
185 assert "Detail" in swagger["definitions"]
186 assert "detail" in swagger["definitions"]["Detail"]["properties"]
187 responses = swagger["paths"]["/details/{id}/"]["get"]["responses"]
188 assert "404" in responses
189 assert responses["404"]["schema"]["$ref"] == "#/definitions/Detail"
190
191
192 def test_url_order():
193 # this view with description override should show up in the schema ...
194 @swagger_auto_schema(method="get", operation_description="description override")
195 @api_view()
196 def test_override(request, pk=None):
197 return Response({"message": "Hello, world!"})
198
199 # ... instead of this view which appears later in the url patterns
200 @api_view()
201 def test_view(request, pk=None):
202 return Response({"message": "Hello, world!"})
203
204 patterns = [
205 path("test/", test_override),
206 path("test/", test_view),
207 ]
208
209 generator = OpenAPISchemaGenerator(
210 info=openapi.Info(title="Test generator", default_version="v1"),
211 version="v2",
212 url="",
213 patterns=patterns,
214 )
215
216 # description override is successful
217 swagger = generator.get_schema(public=True)
218 assert swagger["paths"]["/test/"]["get"]["description"] == "description override"
219
220 # get_endpoints only includes one endpoint
221 endpoints = generator.get_endpoints(None)
222 assert len(endpoints["/test/"][1]) == 1
223
224
225 try:
226 from rest_framework.decorators import MethodMapper, action
227 except ImportError:
228 action = MethodMapper = None
229
230
231 @pytest.mark.skipif(
232 not MethodMapper or not action,
233 reason="action.mapping test (djangorestframework>=3.9 required)",
234 )
235 def test_action_mapping():
236 class ActionViewSet(viewsets.ViewSet):
237 @swagger_auto_schema(method="get", operation_id="mapping_get")
238 @swagger_auto_schema(method="delete", operation_id="mapping_delete")
239 @action(detail=False, methods=["get", "delete"], url_path="test")
240 def action_main(self, request):
241 """mapping docstring get/delete"""
242 pass
243
244 @swagger_auto_schema(operation_id="mapping_post")
245 @action_main.mapping.post
246 def action_post(self, request):
247 """mapping docstring post"""
248 pass
249
250 router = routers.DefaultRouter()
251 router.register(r"action", ActionViewSet, **_basename_or_base_name("action"))
252
253 generator = OpenAPISchemaGenerator(
254 info=openapi.Info(title="Test generator", default_version="v1"),
255 version="v2",
256 url="",
257 patterns=router.urls,
258 )
259
260 for _ in range(3):
261 swagger = generator.get_schema(public=True)
262 action_ops = swagger["paths"]["/test/"]
263 methods = ["get", "post", "delete"]
264 assert all(mth in action_ops for mth in methods)
265 assert all(
266 action_ops[mth]["operationId"] == "mapping_" + mth for mth in methods
267 )
268 assert action_ops["post"]["description"] == "mapping docstring post"
269 assert action_ops["get"]["description"] == "mapping docstring get/delete"
270 assert action_ops["delete"]["description"] == "mapping docstring get/delete"
271
272
273 @pytest.mark.parametrize(
274 "choices, expected_type",
275 [
276 (["A", "B"], openapi.TYPE_STRING),
277 (["A", "B"], openapi.TYPE_STRING),
278 ([123, 456], openapi.TYPE_INTEGER),
279 ([1.2, 3.4], openapi.TYPE_NUMBER),
280 (["A", 456], openapi.TYPE_STRING),
281 ],
282 )
283 def test_choice_field(choices, expected_type):
284 class DetailSerializer(serializers.Serializer):
285 detail = serializers.ChoiceField(choices)
286
287 class DetailViewSet(viewsets.ViewSet):
288 @swagger_auto_schema(responses={200: openapi.Response("OK", DetailSerializer)})
289 def retrieve(self, request, pk=None):
290 return Response({"detail": None})
291
292 router = routers.DefaultRouter()
293 router.register(r"details", DetailViewSet, **_basename_or_base_name("details"))
294
295 generator = OpenAPISchemaGenerator(
296 info=openapi.Info(title="Test generator", default_version="v1"),
297 patterns=router.urls,
298 )
299
300 swagger = generator.get_schema(public=True)
301 property_schema = swagger["definitions"]["Detail"]["properties"]["detail"]
302
303 assert property_schema == openapi.Schema(
304 title="Detail", type=expected_type, enum=choices
305 )
306
307
308 @pytest.mark.parametrize(
309 "choices, field, expected_type",
310 [
311 ([1, 2, 3], models.IntegerField, openapi.TYPE_INTEGER),
312 (["A", "B"], models.CharField, openapi.TYPE_STRING),
313 ],
314 )
315 def test_nested_choice_in_array_field(choices, field, expected_type):
316 # Create a model class on the fly to avoid warnings about using the several
317 # model class name several times
318 model_class = type(
319 "%sModel" % field.__name__,
320 (fake_models.FakeModel,),
321 {
322 "array": postgres_fields.ArrayField(
323 field(choices=((i, "choice %s" % i) for i in choices))
324 ),
325 "__module__": "test_models",
326 },
327 )
328
329 class ArraySerializer(serializers.ModelSerializer):
330 class Meta:
331 model = model_class
332 fields = ("array",)
333
334 class ArrayViewSet(viewsets.ModelViewSet):
335 serializer_class = ArraySerializer
336
337 router = routers.DefaultRouter()
338 router.register(r"arrays", ArrayViewSet, **_basename_or_base_name("arrays"))
339
340 generator = OpenAPISchemaGenerator(
341 info=openapi.Info(title="Test array model generator", default_version="v1"),
342 patterns=router.urls,
343 )
344
345 swagger = generator.get_schema(public=True)
346 property_schema = swagger["definitions"]["Array"]["properties"]["array"]["items"]
347 assert property_schema == openapi.Schema(
348 title="Array", type=expected_type, enum=choices
349 )
350
351
352 def test_json_field():
353 class TestJSONFieldSerializer(serializers.Serializer):
354 json = serializers.JSONField()
355
356 class JSONViewSet(viewsets.ModelViewSet):
357 serializer_class = TestJSONFieldSerializer
358
359 router = routers.DefaultRouter()
360 router.register(r"jsons", JSONViewSet, **_basename_or_base_name("jsons"))
361
362 generator = OpenAPISchemaGenerator(
363 info=openapi.Info(title="Test json field generator", default_version="v1"),
364 patterns=router.urls,
365 )
366
367 swagger = generator.get_schema(public=True)
368 property_schema = swagger["definitions"]["TestJSONField"]["properties"]["json"]
369 assert property_schema == openapi.Schema(title="Json", type=openapi.TYPE_OBJECT)
370
371
372 @pytest.mark.parametrize(
373 "py_type, expected_type",
374 [
375 (str, openapi.TYPE_STRING),
376 (int, openapi.TYPE_INTEGER),
377 (float, openapi.TYPE_NUMBER),
378 (bool, openapi.TYPE_BOOLEAN),
379 ],
380 )
381 def test_optional_return_type(py_type, expected_type):
382 class OptionalMethodSerializer(serializers.Serializer):
383 x = serializers.SerializerMethodField()
384
385 def get_x(self, instance) -> typing.Optional[py_type]:
386 pass
387
388 class OptionalMethodViewSet(viewsets.ViewSet):
389 @swagger_auto_schema(
390 responses={200: openapi.Response("OK", OptionalMethodSerializer)}
391 )
392 def retrieve(self, request, pk=None):
393 return Response({"optional": None})
394
395 router = routers.DefaultRouter()
396 router.register(
397 r"optional", OptionalMethodViewSet, **_basename_or_base_name("optional")
398 )
399
400 generator = OpenAPISchemaGenerator(
401 info=openapi.Info(title="Test optional parameter", default_version="v1"),
402 patterns=router.urls,
403 )
404 swagger = generator.get_schema(public=True)
405 property_schema = swagger["definitions"]["OptionalMethod"]["properties"]["x"]
406 assert property_schema == openapi.Schema(
407 title="X", type=expected_type, readOnly=True, x_nullable=True
408 )
409
410
411 @pytest.mark.skipif(
412 sys.version_info < (3, 12), reason="PEP-695 requires Python 3.12 or higher"
413 )
414 def test_pep695_with_pep563():
415 from pep695_with_pep563 import RetrieveView
416
417 swagger = OpenAPISchemaGenerator(
418 info=openapi.Info(title="Test", default_version="v1"),
419 patterns=[path("/int/", RetrieveView[int].as_view())],
420 ).get_schema(public=True)
421 property_schema = swagger["definitions"]["Generic"]["properties"]["value"]
422 assert property_schema == openapi.Schema(
423 title="Value", type=openapi.TYPE_STRING, readOnly=True
424 )
425
426
427 EXPECTED_DESCRIPTION = """\
428 description: |-
429 This is a demo project for the [drf-yasg](https://github.com/axnsan12/drf-yasg) Django Rest Framework library.
430
431 The `swagger-ui` view can be found [here](/cached/swagger).
432 The `ReDoc` view can be found [here](/cached/redoc).
433 The swagger YAML document can be found [here](/cached/swagger.yaml).
434 """ # noqa: E501
435
436
437 def test_multiline_strings(call_generate_swagger):
438 output = call_generate_swagger(format="yaml")
439 print("|\n|".join(output.splitlines()[:20]))
440 assert EXPECTED_DESCRIPTION in output