apidoc: Slashes in prefix being transformed to &gt by schema_links template tag;

[Doug]

Hi All,
First of all, I love DRF so many thanks to all the developers involved in
bringing such a wonderful framework into being.

I have been developing an API for work that has to offer some backwards
compatibility with a legacy API. I've had to defined the following
DefaultRouter with two routes. The modern API route prefix "*vendors*" and
the legacy API route prefix "*kicker/api/vendor*":

router = routers.DefaultRouter()
router.register(r*'vendors'*, views.VendorViewSet, 'vendors')
# Legacy Kicker API partial compatibility for HTTP GET of vendors.
router.register(r*'kicker/api/vendor'*, views.VendorViewSet,
'legacy-vendors')

urlpatterns = [
url(r'^', include_docs_urls(title="Kicker-lite API",
... Lines omitted for brevity...
url(r'^', include(router.urls)),
]


I like to have my API documentation at the root endpoint so people don't
have to know any endpoints in order to learn to use the API and this works
very well.

When I visit my root end-point I get beautiful API documentation and
working endpoints with working "Interact" buttons but the code examples for
my legacy endpoints are slightly corrupted:

# Interact with the API endpoint
$ coreapi action *kicker api > vendor > list*


I've managed to find the culprit which is attempting to switch my prefix of
"*kicker/api/vendors*" to having greater-than symbols here:

https://github.com/encode/django-rest-framework/blob/master/rest_framework/templatetags/rest_framework.py#L265



@register.filter
def schema_links(section, sec_key=None):
"""
Recursively find every link in a schema, even nested.
"""
*NESTED_FORMAT = '%s > %s' # this format is used in docs/js/api.js:normalizeKeys*
links = section.links
if section.data:
data = section.data.items()
for sub_section_key, sub_section in data:
new_links = schema_links(sub_section, sec_key=sub_section_key)
links.update(new_links)

if sec_key is not None:
new_links = OrderedDict()
for link_key, link in links.items():
*new_key = NESTED_FORMAT % (sec_key, link_key)*
new_links.update({new_key: link})
return new_links

return links


I'm not sure why these are appearing as urlencoded > but I wondered if
anyone had any ideas how I can avoid DRF transforming my prefix slashes
into greater-than symbols in the first place?

Any help hugely appreciated.

Cheers,

Doug

[Daniel Cannon]

Did you ever happen to find a solution for this? I'm encountering the same
problem.

Post by Doug
Hi All,
First of all, I love DRF so many thanks to all the developers involved in
bringing such a wonderful framework into being.
I have been developing an API for work that has to offer some backwards
compatibility with a legacy API. I've had to defined the following
DefaultRouter with two routes. The modern API route prefix "*vendors*"
router = routers.DefaultRouter()
router.register(r*'vendors'*, views.VendorViewSet, 'vendors')
# Legacy Kicker API partial compatibility for HTTP GET of vendors.
router.register(r*'kicker/api/vendor'*, views.VendorViewSet,
'legacy-vendors')
urlpatterns = [
url(r'^', include_docs_urls(title="Kicker-lite API",
... Lines omitted for brevity...
url(r'^', include(router.urls)),
]
I like to have my API documentation at the root endpoint so people don't
have to know any endpoints in order to learn to use the API and this works
very well.
When I visit my root end-point I get beautiful API documentation and
working endpoints with working "Interact" buttons but the code examples for
# Interact with the API endpoint
I've managed to find the culprit which is attempting to switch my prefix
https://github.com/encode/django-rest-framework/blob/master/rest_framework/templatetags/rest_framework.py#L265
@register.filter
"""
Recursively find every link in a schema, even nested.
"""
*NESTED_FORMAT = '%s > %s' # this format is used in docs/js/api.js:normalizeKeys*
links = section.links
data = section.data.items()
new_links = schema_links(sub_section, sec_key=sub_section_key)
links.update(new_links)
new_links = OrderedDict()
*new_key = NESTED_FORMAT % (sec_key, link_key)*
new_links.update({new_key: link})
return new_links
return links
anyone had any ideas how I can avoid DRF transforming my prefix slashes
into greater-than symbols in the first place?
Any help hugely appreciated.
Cheers,
Doug

[Doug Scoular]

Hi Daniel,

Post by Daniel Cannon
Did you ever happen to find a solution for this? I'm encountering the same
problem.

I'm afraid not. I'm quite surprised that I never got any response.

I have to say that I love the *rest_framework.documentation* module and its
*include_docs_urls() *method, very few people seem to use this or know
about it but I think it is even more attractive than swagger or any of the
other third-party documentation modules. I always make it the root of my
API.

I think the big problem is that the DRF tutorial doesn't refer to the
documentation module at all but defaults to using the, perhaps, inferior
BrowsableAPIRender. That may be the reason I haven't had much in the way of
a response.

The documentation module is very well documented at:

https://www.django-rest-framework.org/topics/documenting-your-api/


None of my colleagues have been aware of it and all use swagger or other
third-party documentation modules.

This is a hidden treasure in the DRF armament IMHO.

Cheers,

Doug