diff --git a/CHANGELOG.rst b/CHANGELOG.rst index f7637393..b4b4d934 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -7,18 +7,18 @@ Changelog - Added ``detype_patterns()`` with ``@cache``. [Nick Pope] - add "externalDocs" to operation via extend_schema `#681 `_ - warn on invalid components names `#685 `_ -- wrap examples in list/pagination when serializer is many=True `#641 `_ `#640 `_ `#595 `_ +- wrap examples in list/pagination when serializer is many=True `#641 `_ `#640 `_ `#595 `_ - python's and django's float is really "double precision" `#674 `_ - Support negative numbers in pattern regex for coerced decimal fields [Mike Hansen] - add OpenAPI callback operations `#665 `_ - Keep the urlpatterns in the apiview and pass it to the generator [Jorge Cardona] - django-filter: raise priority of explicitly given filter method type hints `#660 `_ - also allow @extend_schema_field on django-filter filter method `#660 `_ -- accommodate pyright limitations `#657 `_ -- fix doc extraction for built-in types `#654 `_ +- accommodate pyright limitations `#657 `_ +- fix doc extraction for built-in types `#654 `_ - use get_doc for description [Josh Ferge] - add more information to resolved TypedDicts [Josh Ferge] -- fix url escaping bug introduced in `#556 `_ (`#650 `_) +- fix url escaping bug introduced in `#556 `_ (`#650 `_) - pass through version from UI to schema endpoint `#650 `_ - factor out schema_url generation `#650 `_ - relax AcceptHeaderVersioning contraint for modification `#650 `_ @@ -50,7 +50,7 @@ Breaking changes / important additions: ------------------- - add root level extension setting `#619 `_ -- ease schema browser handling with "Content-Disposition" `#607 `_ +- ease schema browser handling with "Content-Disposition" `#607 `_ - custom settings per SpectacularAPIView instance `#365 `_ - Support new X | Y union syntax in Python 3.10 (PEP 604) [Marti Raudsepp] - upstream release updates, compat test fix for jwt, consistency fix @@ -70,12 +70,12 @@ Breaking changes / important additions: - add renderer & parser whitelist setting `#598 `_ - catch attr exception for invalid SerializerMethodField `#592 `_ -- add regression test for catch-all status codes `#573 `_ +- add regression test for catch-all status codes `#573 `_ - bugfix OpenApiResponse without description argument `#591 `_ - introduce direction literal / import consolidation `#582 `_ - mitigate CORS issues for external requests in Swagger UI `#588 `_ - Swagger UI authorized schema retrieval `#342 `_ `#458 `_ -- remove cyclic import warning as fixes haves mitigated the issue. `#581 `_ +- remove cyclic import warning as fixes haves mitigated the issue. `#581 `_ - bugfix: anchor parameter patterns with ^$ - bugfix isolation of derivatives for @extend_schema_serializer/@extend_schema_field `#585 `_ - add support for djangorestframework-recursive `#586 `_ @@ -104,8 +104,8 @@ Breaking changes / important additions: - bugfix COMPONENT_SPLIT_REQUEST for empty req/resp serializers `#572 `_ - Make it cleared that ENUM_NAME_OVERRIDES is a key within SPECTACULAR_SETTINGS [johnthagen] - Improve formatting in customization docs [johnthagen] -- bugfix @extend_schema_view on @api_view `#554 `_ -- bugfix isolation for @extend_schema/@extend_schema_view reorg `#554 `_ +- bugfix @extend_schema_view on @api_view `#554 `_ +- bugfix isolation for @extend_schema/@extend_schema_view reorg `#554 `_ - Fix inheritance bugs with @extend_schema_view(). [Nick Pope] - Allow methods in @extend_schema to be case insensitive. [Nick Pope] - Added a documentation blueprint for RapiDoc. [Nick Pope] @@ -164,13 +164,13 @@ Breaking changes / important additions: 0.19.0 (2021-09-21) ------------------- -- fix/cleanup suffixed path variable coercion `#516 `_ +- fix/cleanup suffixed path variable coercion `#516 `_ - remove superseded Request mock from oauth_toolkit -- be gracious on Enums that are not recognized by DRF `#500 `_ +- be gracious on Enums that are not recognized by DRF `#500 `_ - remove non-required empty descriptions -- added test case for lookup_field `#524 `_ +- added test case for lookup_field `#524 `_ - Fix grammatical typo [johnthagen] -- remove mapping for re.Pattern (no 3.6 and mypy issues) `#526 `_ +- remove mapping for re.Pattern (no 3.6 and mypy issues) `#526 `_ - Add missing types defined in specification. [Nick Pope] - Add type mappings for IP4, IP6, TIME & DURATION. [Nick Pope] - add support for custom converters and coverter override `#502 `_ @@ -179,23 +179,23 @@ Breaking changes / important additions: - lazy settings loading in drainage - Improve guide for migration from drf-yasg. [Nick Pope] - handle default value for SerializerMethodField `#422 `_ -- consolidate bearer scheme generation & bugfix `#515 `_ +- consolidate bearer scheme generation & bugfix `#515 `_ - prevent uncaught exception on modified django-filter `#519 `_ -- add decoupled model docstrings `#522 `_ +- add decoupled model docstrings `#522 `_ - Fix warnings raised during testing. [Nick Pope] - add name override to @extend_schema_serializer `#517 `_ - Fix deprecation warning about default_app_config from Django 3.2+ [Janne Rönkkö] - Remove obsolete value from IMPORT_STRINGS. [Nick Pope] - Add extension for TokenVerifySerializer. [Nick Pope] - Use SESSION_COOKIE_NAME in SessionScheme. [Nick Pope] -- add regex path parameter extraction for explicit cases `#510 `_ -- honor lookup_url_kwarg name customization `#509 `_ +- add regex path parameter extraction for explicit cases `#510 `_ +- honor lookup_url_kwarg name customization `#509 `_ - add contrib compat tests for drf-nested-routers - improve path coersion model resolution -- add test_fields API response test `#501 `_ +- add test_fields API response test `#501 `_ - Handle 'lookup_field' containing relationships for path parameters [Luke Plant] -- add BinaryField case to tests `#506 `_ -- fix: BinaryField's schema type should be string `#505 `_ (`#506 `_) [jtamm-red] +- add BinaryField case to tests `#506 `_ +- fix: BinaryField's schema type should be string `#505 `_ (`#506 `_) [jtamm-red] - bugfix incomplete regex stripping for literal dots `#507 `_ - Fix tests [Jameel Al-Aziz] - Fix type hint support for functools cached_property wrapped funcs [Jameel Al-Aziz] @@ -288,7 +288,7 @@ Breaking changes / important additions: ------------------- - prevent endless loop in extensions when augmenting schema `#426 `_ -- bugfix secondary import cycle (generics.APIView) `#430 `_ +- bugfix secondary import cycle (generics.APIView) `#430 `_ - fix: avoid circular import of/via rest_framework's APIView [Daniel Hahler] Breaking changes / important additions: @@ -321,7 +321,7 @@ Breaking changes / important additions: - improve type hint detection for Iterable and NamedTuple `#404 `_ - bugfix ReadOnlyField when used as ListSerlializer child `#404 `_ - improve component discard logic `#395 `_ -- allow disabling operation sorting for sorting in PREPROCESSIN_HOOKS `#410 `_ +- allow disabling operation sorting for sorting in PREPROCESSIN_HOOKS `#410 `_ - add regression test for `#407 `_ - fix error on read-only serializer [Matthieu Treussart] - invert component exclusion logic (OpenApiSerializerExtension) `#351 `_ `#391 `_ @@ -342,9 +342,9 @@ Breaking changes / important additions: ------------------- - add redoc dist setting -- bugfix mock request asymmetry `#370 `_ `#250 `_ +- bugfix mock request asymmetry `#370 `_ `#250 `_ - refactor urlpattern simplification `#373 `_ `#168 `_ -- include relation PKs into SCHEMA_COERCE_PATH_PK handling `#251 `_ +- include relation PKs into SCHEMA_COERCE_PATH_PK handling `#251 `_ - allow PolymorphicProxySerializer to be simple 'oneOf' - bugfix incorrect PolymorphicProxySerializer warning on extend_schema_field `#263 `_ - add break-out option for SerializerFieldExtension @@ -380,8 +380,8 @@ Breaking changes / important additions: - Fixed traversing of 'Optional' type annotations [Luke Plant] - prevent pagination on error responses. `#277 `_ - fix SCHEMA_PATH_PREFIX_TRIM ^/ pitfall & remove unused old URL mounting -- slighly improve `#332 `_ for django-filter range filters -- introduce non-redundant title field. `#191 `_ `#286 `_ +- slighly improve `#332 `_ for django-filter range filters +- introduce non-redundant title field. `#191 `_ `#286 `_ - improve schema version string handling including variations `#303 `_ - bugfix ENUM_NAME_OVERRIDES for categorized choices `#339 `_ - improve SCHEMA_PATH_PREFIX handling, add auto-detect default, introduce prefix trimming `#336 `_ @@ -412,8 +412,8 @@ Breaking changes / important additions: - handle Decimals for YAML `#316 `_ - remove deprecated django-filter backend solution - update swagger-ui version -- bugfix [] case and lint `#312 `_ -- discriminate None and typing.Any usage `#315 `_ +- bugfix [] case and lint `#312 `_ +- discriminate None and typing.Any usage `#315 `_ - fix multi-step source relation field resolution, again. `#274 `_ `#296 `_ - Add any type for OpenApiTypes [André da Silva] - improve Extension usage documentation `#307 `_ @@ -507,7 +507,7 @@ Breaking changes: - bugfix/restore optional default parameter value `#226 `_ - Include QuerySerializer in documentation [KimSoungRyoul] - support OAS3.0 ExampleObject to @extend_schema & @extend_schema_serializer `#115 `_ [KimSoungRyoul] -- add explicit double and int32 types. `#214 `_ +- add explicit double and int32 types. `#214 `_ - added type extension for int64 format support [Peter Dreuw] - fix TokenAuthentication handling of keyword `#205 `_ - Allow callable limit_value in schema [Serkan Hosca] @@ -593,7 +593,7 @@ Breaking changes: - Hot fix for AcceptVersioningHeader support [Nicolas Delaby] - bugfix module string includes with urlpatterns `#157 `_ - add expressive error in case of misconfiguration `#156 `_ -- fix django-filter related resolution. improve test `#150 `_ `#151 `_ +- fix django-filter related resolution. improve test `#150 `_ `#151 `_ - improve follow_field_source for reverse resolution and model leafs `#150 `_ - add ref if list field child is serializer [Matt Shirley] - add customization option for mock request generation `#135 `_ @@ -681,7 +681,7 @@ Breaking changes: - bugfix attr typo with Token auth extension `#99 `_ - improve docstring extraction `#96 `_ - Manual polymorphic [Jair Henrique] -- Add summary field to extend_schema `#97 `_ [lilisha100] +- Add summary field to extend_schema `#97 `_ [lilisha100] - reduce minimal package requirements - extend sdist with tests & doc - bugfix nested RO/WO serializer on COMPONENT_SPLIT_REQUEST @@ -702,7 +702,7 @@ Breaking changes: ------------------ - put contrib code in packages named files -- improve djangorestframework-camel-case support `#73 `_ +- improve djangorestframework-camel-case support `#73 `_ - Add support to djangorestframework-camel-case [Jair Henrique] - ENUM_NAME_OVERRIDES accepts import string for easier handling `#70 `_ - honor versioning on schema UIs `#71 `_ @@ -710,7 +710,7 @@ Breaking changes: - provide global enum naming. `#70 `_ - refactor choice field - remove unused sorter setting -- improve FileField, add test and documentation. `#69 `_ +- improve FileField, add test and documentation. `#69 `_ - Fix file fields [John Vandenberg] - allow for functions on models beside properties. `#68 `_ - replace removed DRF compat function @@ -788,7 +788,7 @@ Breaking changes: - Parse path parameter type hints from url. closes `#34 `_ - Consolidate duplicate warnings/add error `#28 `_ - Prevent warning for DRF format suffix param -- Improve ACCEPT header handling `#42 `_ +- Improve ACCEPT header handling `#42 `_ Breaking changes: @@ -868,7 +868,7 @@ Breaking changes: - Warn on duplicate serializer names. - Added explicit exclude flag for operation. - Bugfix: PrimaryKeyRelatedField(read_only=True) failing to find type. -- Change operation sorting to alphanumeric with option (`#6 `_) +- Change operation sorting to alphanumeric with option (`#6 `_) - Robustify serializer field support for ``@extend_schema_field``. - Enable field serializers support. [p.g.alekseev] - Adding custom tags support [p.g.alekseev] diff --git a/README.rst b/README.rst index 4b71a4d1..bd02131a 100644 --- a/README.rst +++ b/README.rst @@ -37,7 +37,7 @@ Features - Callback operations (experimental) - Included support for: - `django-polymorphic `_ / `django-rest-polymorphic `_ - - `SimpleJWT `_ + - `SimpleJWT `_ - `DjangoOAuthToolkit `_ - `djangorestframework-jwt `_ (tested fork `drf-jwt `_) - `dj-rest-auth `_ (maintained fork of `django-rest-auth `_) @@ -48,7 +48,7 @@ Features - `djangorestframework-dataclasses `_ -For more information visit the `documentation `_. +For more information visit the `documentation `_. License ------- @@ -289,16 +289,16 @@ globally, and then simply run: .. _Django REST framework: https://www.django-rest-framework.org/ .. _OpenAPI 3.0: https://github.com/OAI/OpenAPI-Specification -.. _tox: http://tox.readthedocs.org/en/latest/ +.. _tox: https://tox.wiki/en/latest/ .. _drf-spectacular-sidecar: https://github.com/tfranzel/drf-spectacular-sidecar .. |build-status| image:: https://github.com/tfranzel/drf-spectacular/actions/workflows/ci.yml/badge.svg :target: https://github.com/tfranzel/drf-spectacular/actions/workflows/ci.yml .. |pypi-version| image:: https://img.shields.io/pypi/v/drf-spectacular.svg - :target: https://pypi.python.org/pypi/drf-spectacular -.. |codecov| image:: https://codecov.io/gh/tfranzel/drf-spectacular/branch/master/graph/badge.svg - :target: https://codecov.io/gh/tfranzel/drf-spectacular + :target: https://pypi.org/project/drf-spectacular/ +.. |codecov| image:: https://app.codecov.io/gh/tfranzel/drf-spectacular/branch/master/graph/badge.svg + :target: https://app.codecov.io/gh/tfranzel/drf-spectacular .. |docs| image:: https://readthedocs.org/projects/drf-spectacular/badge/ - :target: https://drf-spectacular.readthedocs.io/ + :target: https://drf-spectacular.readthedocs.io/en/latest/ .. |pypi-dl| image:: https://img.shields.io/pypi/dm/drf-spectacular :target: https://pypi.org/project/drf-spectacular/ diff --git a/docs/client_generation.rst b/docs/client_generation.rst index f793fcfc..5e43057b 100644 --- a/docs/client_generation.rst +++ b/docs/client_generation.rst @@ -59,8 +59,11 @@ field. Even though it is the correct way (according to the specification), it sa Setting ``'ENUM_ADD_EXPLICIT_BLANK_NULL_CHOICE': False`` will create a less accurate schema that tends to offend fewer generator targets. -For more information please refer to the `official documentation `_ and -more specifically the `specification proposal `_. +For more information please refer to the `official documentation`__ and more specifically the `specification +proposal`__. + +__ https://swagger.io/docs/specification/data-models/enums/ +__ https://github.com/OAI/OpenAPI-Specification/blob/main/proposals/2019-10-31-Clarify-Nullable.md#user-content-if-a-schema-specifies-nullable-true-and-enum-1-2-3-does-that-schema-allow-null-values-see-1900 Relevant settings: diff --git a/docs/conf.py b/docs/conf.py index f22c94f7..7f63fc56 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -48,6 +48,13 @@ default_role = 'default-role-error' +linkcheck_ignore = [ + # Special-use addresses and domain names. (RFC 6761/6890) + r"^https?://(?:127\.0\.0\.1|\[::1\])(?::\d+)?/", + r"^https?://(?:[^/\.]+\.)*example\.(?:com|net|org)(?::\d+)?/", + r"^https?://(?:[^/\.]+\.)*(?:example|invalid|localhost|test)(?::\d+)?/", +] + nitpicky = True nitpick_ignore_regex = [ diff --git a/drf_spectacular/extensions.py b/drf_spectacular/extensions.py index f424ece9..74767c70 100644 --- a/drf_spectacular/extensions.py +++ b/drf_spectacular/extensions.py @@ -23,7 +23,7 @@ class OpenApiAuthenticationExtension(OpenApiGeneratorExtension['OpenApiAuthentic set a higher matching priority by setting the class attribute ``priority = 1`` or higher. ``get_security_definition()`` is expected to return a valid `OpenAPI security scheme object - `_ + `_ """ _registry: List['OpenApiAuthenticationExtension'] = [] @@ -51,7 +51,7 @@ class OpenApiSerializerExtension(OpenApiGeneratorExtension['OpenApiSerializerExt can be accessed via ``self.target``. ``map_serializer()`` is expected to return a valid `OpenAPI schema object - `_. + `_. """ _registry: List['OpenApiSerializerExtension'] = [] @@ -74,7 +74,7 @@ class OpenApiSerializerFieldExtension(OpenApiGeneratorExtension['OpenApiSerializ warnings, in which case manual construction is advisable. ``map_serializer_field()`` is expected to return a valid `OpenAPI schema object - `_. + `_. """ _registry: List['OpenApiSerializerFieldExtension'] = [] @@ -119,7 +119,7 @@ class OpenApiFilterExtension(OpenApiGeneratorExtension['OpenApiFilterExtension'] ``get_schema_operation_parameters()`` is expected to return either an empty list or a list of valid raw `OpenAPI parameter objects - `_. + `_. Using ``drf_spectacular.plumbing.build_parameter_type`` is recommended to generate the appropriate raw dict objects. """ diff --git a/drf_spectacular/settings.py b/drf_spectacular/settings.py index fd43f53f..554d9dca 100644 --- a/drf_spectacular/settings.py +++ b/drf_spectacular/settings.py @@ -158,7 +158,7 @@ 'ENABLE_DJANGO_DEPLOY_CHECK': True, # General schema metadata. Refer to spec for valid inputs - # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#openapi-object + # https://spec.openapis.org/oas/v3.0.3#openapi-object 'TITLE': '', 'DESCRIPTION': '', 'TOS': None, @@ -188,7 +188,7 @@ 'EXTENSIONS_ROOT': {}, # Oauth2 related settings. used for example by django-oauth2-toolkit. - # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#oauth-flows-object + # https://spec.openapis.org/oas/v3.0.3#oauth-flows-object 'OAUTH2_FLOWS': [], 'OAUTH2_AUTHORIZATION_URL': None, 'OAUTH2_TOKEN_URL': None,