| 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 |