Changeset View
Changeset View
Standalone View
Standalone View
swh/web/api/apidoc.py
# Copyright (C) 2015-2020 The Software Heritage developers | # Copyright (C) 2015-2022 The Software Heritage developers | ||||
# See the AUTHORS file at the top-level directory of this distribution | # See the AUTHORS file at the top-level directory of this distribution | ||||
# License: GNU Affero General Public License version 3, or any later version | # License: GNU Affero General Public License version 3, or any later version | ||||
# See top-level LICENSE file for more information | # See top-level LICENSE file for more information | ||||
from collections import defaultdict | from collections import defaultdict | ||||
import functools | import functools | ||||
from functools import wraps | from functools import wraps | ||||
import os | import os | ||||
import re | import re | ||||
import textwrap | import textwrap | ||||
from typing import List | from typing import List | ||||
import docutils.nodes | import docutils.nodes | ||||
import docutils.parsers.rst | import docutils.parsers.rst | ||||
import docutils.utils | import docutils.utils | ||||
from django.shortcuts import redirect | |||||
from rest_framework.decorators import api_view | from rest_framework.decorators import api_view | ||||
from swh.web.api.apiresponse import make_api_response | from swh.web.api.apiresponse import make_api_response | ||||
from swh.web.api.apiurls import APIUrls, CategoryId | from swh.web.api.apiurls import APIUrls, CategoryId | ||||
from swh.web.utils import parse_rst | from swh.web.utils import parse_rst, reverse | ||||
class _HTTPDomainDocVisitor(docutils.nodes.NodeVisitor): | class _HTTPDomainDocVisitor(docutils.nodes.NodeVisitor): | ||||
""" | """ | ||||
docutils visitor for walking on a parsed docutils document containing sphinx | docutils visitor for walking on a parsed docutils document containing sphinx | ||||
httpdomain roles. Its purpose is to extract relevant info regarding swh | httpdomain roles. Its purpose is to extract relevant info regarding swh | ||||
api endpoints (for instance url arguments) from their docstring written | api endpoints (for instance url arguments) from their docstring written | ||||
using sphinx httpdomain; and produce the main description back into a ReST | using sphinx httpdomain; and produce the main description back into a ReST | ||||
▲ Show 20 Lines • Show All 332 Lines • ▼ Show 20 Lines | def decorator(f): | ||||
# create a dedicated view to display endpoint HTML doc | # create a dedicated view to display endpoint HTML doc | ||||
@api_view(["GET", "HEAD"]) | @api_view(["GET", "HEAD"]) | ||||
@wraps(f) | @wraps(f) | ||||
def doc_view(request): | def doc_view(request): | ||||
doc_data = get_doc_data(f, route, noargs) | doc_data = get_doc_data(f, route, noargs) | ||||
return make_api_response(request, None, doc_data) | return make_api_response(request, None, doc_data) | ||||
route_name = "%s-doc" % route[1:-1].replace("/", "-") | route_name = "%s-doc" % route[1:-1].replace("/", "-") | ||||
urlpattern = f"^{api_version}{route}doc/$" | urlpattern = f"^api/{api_version}{route}doc/$" | ||||
view_name = "api-%s-%s" % (api_version, route_name) | view_name = "api-%s-%s" % (api_version, route_name) | ||||
APIUrls.add_url_pattern(urlpattern, doc_view, view_name) | APIUrls.add_url_pattern(urlpattern, doc_view, view_name) | ||||
# for backward compatibility as previous apidoc URLs were missing | |||||
# the /api prefix | |||||
old_view_name = view_name.replace("api-", "") | |||||
old_urlpattern = f"^{api_version}{route}doc/$" | |||||
@api_view(["GET", "HEAD"]) | |||||
def old_doc_view(request): | |||||
return redirect(reverse(view_name)) | |||||
APIUrls.add_url_pattern(old_urlpattern, old_doc_view, old_view_name) | |||||
@wraps(f) | @wraps(f) | ||||
def documented_view(request, **kwargs): | def documented_view(request, **kwargs): | ||||
doc_data = get_doc_data(f, route, noargs) | doc_data = get_doc_data(f, route, noargs) | ||||
try: | try: | ||||
return {"data": f(request, **kwargs), "doc_data": doc_data} | return {"data": f(request, **kwargs), "doc_data": doc_data} | ||||
except Exception as exc: | except Exception as exc: | ||||
exc.doc_data = doc_data | exc.doc_data = doc_data | ||||
raise exc | raise exc | ||||
▲ Show 20 Lines • Show All 92 Lines • Show Last 20 Lines |