diff --git a/swh/web/api/apidoc.py b/swh/web/api/apidoc.py --- a/swh/web/api/apidoc.py +++ b/swh/web/api/apidoc.py @@ -367,8 +367,25 @@ return data +DOC_COMMON_HEADERS = ''' + :reqheader Accept: the requested response content type, + either ``application/json`` (default) or ``application/yaml`` + :resheader Content-Type: this depends on :http:header:`Accept` + header of request''' +DOC_RESHEADER_LINK = ''' + :resheader Link: indicates that a subsequent result page is + available and contains the url pointing to it +''' + +DEFAULT_SUBSTITUTIONS = { + 'common_headers': DOC_COMMON_HEADERS, + 'resheader_link': DOC_RESHEADER_LINK, +} + + def format_docstring(**substitutions): def decorator(f): - f.__doc__ = f.__doc__.format(**substitutions) + f.__doc__ = f.__doc__.format(**{ + **DEFAULT_SUBSTITUTIONS, **substitutions}) return f return decorator diff --git a/swh/web/api/views/content.py b/swh/web/api/views/content.py --- a/swh/web/api/views/content.py +++ b/swh/web/api/views/content.py @@ -10,7 +10,7 @@ from swh.web.common import service from swh.web.common.utils import reverse from swh.web.common.exc import NotFoundExc -from swh.web.api.apidoc import api_doc +from swh.web.api.apidoc import api_doc, format_docstring from swh.web.api import utils from swh.web.api.apiurls import api_route from swh.web.api.views.utils import api_lookup @@ -19,6 +19,7 @@ @api_route(r'/content/(?P[0-9a-z_:]*[0-9a-f]+)/filetype/', 'api-1-content-filetype', checksum_args=['q']) @api_doc('/content/filetype/') +@format_docstring() def api_content_filetype(request, q): """ .. http:get:: /api/1/content/[(hash_type):](hash)/filetype/ @@ -39,9 +40,7 @@ :>json string mimetype: the detected MIME type of the content :>json object tool: information about the tool used to detect the content filetype - :reqheader Accept: the requested response content type, - either ``application/json`` (default) or ``application/yaml`` - :resheader Content-Type: this depends on :http:header:`Accept` header of request + {common_headers} **Allowed HTTP Methods:** :http:method:`get`, :http:method:`head`, :http:method:`options` @@ -64,6 +63,7 @@ @api_route(r'/content/(?P[0-9a-z_:]*[0-9a-f]+)/language/', 'api-1-content-language', checksum_args=['q']) @api_doc('/content/language/') +@format_docstring() def api_content_language(request, q): """ .. http:get:: /api/1/content/[(hash_type):](hash)/language/ @@ -85,9 +85,7 @@ :>json string lang: the detected programming language if any :>json object tool: information about the tool used to detect the programming language - :reqheader Accept: the requested response content type, - either ``application/json`` (default) or ``application/yaml`` - :resheader Content-Type: this depends on :http:header:`Accept` header of request + {common_headers} **Allowed HTTP Methods:** :http:method:`get`, :http:method:`head`, :http:method:`options` @@ -110,6 +108,7 @@ @api_route(r'/content/(?P[0-9a-z_:]*[0-9a-f]+)/license/', 'api-1-content-license', checksum_args=['q']) @api_doc('/content/license/') +@format_docstring() def api_content_license(request, q): """ .. http:get:: /api/1/content/[(hash_type):](hash)/license/ @@ -129,9 +128,7 @@ :>json array licenses: array of strings containing the detected license names if any :>json object tool: information about the tool used to detect the license - :reqheader Accept: the requested response content type, - either ``application/json`` (default) or ``application/yaml`` - :resheader Content-Type: this depends on :http:header:`Accept` header of request + {common_headers} **Allowed HTTP Methods:** :http:method:`get`, :http:method:`head`, :http:method:`options` @@ -258,6 +255,7 @@ @api_route(r'/content/known/search/', 'api-1-content-known', methods=['POST']) @api_route(r'/content/known/(?P(?!search).*)/', 'api-1-content-known') @api_doc('/content/known/', tags=['hidden']) +@format_docstring() def api_check_content_known(request, q=None): """ .. http:get:: /api/1/content/known/(sha1)[,(sha1), ...,(sha1)]/ @@ -269,9 +267,7 @@ for the content to check existence. Multiple values can be provided separated by ','. - :reqheader Accept: the requested response content type, - either ``application/json`` (default) or ``application/yaml`` - :resheader Content-Type: this depends on :http:header:`Accept` header of request + {common_headers} :>json array search_res: array holding the search result for each provided **sha1** :>json object search_stats: some statistics regarding the number of **sha1** provided @@ -334,6 +330,7 @@ @api_route(r'/content/(?P[0-9a-z_:]*[0-9a-f]+)/', 'api-1-content', checksum_args=['q']) @api_doc('/content/') +@format_docstring() def api_content_metadata(request, q): """ .. http:get:: /api/1/content/[(hash_type):](hash)/ @@ -349,9 +346,7 @@ :param string hash: hexadecimal representation of the checksum value computed with the specified hashing algorithm. - :reqheader Accept: the requested response content type, - either ``application/json`` (default) or ``application/yaml`` - :resheader Content-Type: this depends on :http:header:`Accept` header of request + {common_headers} :>json object checksums: object holding the computed checksum values for the requested content :>json string data_url: link to :http:get:`/api/1/content/[(hash_type):](hash)/raw/` diff --git a/swh/web/api/views/directory.py b/swh/web/api/views/directory.py --- a/swh/web/api/views/directory.py +++ b/swh/web/api/views/directory.py @@ -5,7 +5,7 @@ from swh.web.common import service from swh.web.api import utils -from swh.web.api.apidoc import api_doc +from swh.web.api.apidoc import api_doc, format_docstring from swh.web.api.apiurls import api_route from swh.web.api.views.utils import api_lookup @@ -16,6 +16,7 @@ 'api-1-directory', checksum_args=['sha1_git']) @api_doc('/directory/') +@format_docstring() def api_directory(request, sha1_git, path=None): """ .. http:get:: /api/1/directory/(sha1_git)/[(path)/] @@ -34,9 +35,7 @@ :param string path: optional parameter to get information about the directory entry pointed by that relative path - :reqheader Accept: the requested response content type, - either ``application/json`` (default) or ``application/yaml`` - :resheader Content-Type: this depends on :http:header:`Accept` header of request + {common_headers} :>jsonarr object checksums: object holding the computed checksum values for a directory entry (only for file entries) diff --git a/swh/web/api/views/identifiers.py b/swh/web/api/views/identifiers.py --- a/swh/web/api/views/identifiers.py +++ b/swh/web/api/views/identifiers.py @@ -10,13 +10,14 @@ from swh.web.common import service from swh.web.common.utils import resolve_swh_persistent_id -from swh.web.api.apidoc import api_doc +from swh.web.api.apidoc import api_doc, format_docstring from swh.web.api.apiurls import api_route @api_route(r'/resolve/(?P.*)/', 'api-1-resolve-swh-pid') @api_doc('/resolve/') +@format_docstring() def api_resolve_swh_pid(request, swh_id): """ .. http:get:: /api/1/resolve/(swh_id)/ @@ -37,9 +38,7 @@ :>json string object_type: the type of the pointed object :>json number scheme_version: the scheme version of the persistent identifier - :reqheader Accept: the requested response content type, - either ``application/json`` (default) or ``application/yaml`` - :resheader Content-Type: this depends on :http:header:`Accept` header of request + {common_headers} **Allowed HTTP Methods:** :http:method:`get`, :http:method:`head`, :http:method:`options` diff --git a/swh/web/api/views/origin.py b/swh/web/api/views/origin.py --- a/swh/web/api/views/origin.py +++ b/swh/web/api/views/origin.py @@ -10,7 +10,7 @@ from swh.web.common.exc import BadInputExc from swh.web.common.origin_visits import get_origin_visits from swh.web.common.utils import reverse -from swh.web.api.apidoc import api_doc +from swh.web.api.apidoc import api_doc, format_docstring from swh.web.api.apiurls import api_route from swh.web.api.views.utils import api_lookup @@ -46,6 +46,7 @@ @api_route(r'/origins/', 'api-1-origins') @api_doc('/origins/', noargs=True) +@format_docstring() def api_origins(request): """ .. http:get:: /api/1/origins/ @@ -67,12 +68,8 @@ or ``deposit``) :>jsonarr string url: the origin canonical url - :reqheader Accept: the requested response content type, - either ``application/json`` (default) or ``application/yaml`` - :resheader Content-Type: this depends on :http:header:`Accept` header - of request - :resheader Link: indicates that a subsequent or previous result page - are available and contains the urls pointing to them + {common_headers} + {resheader_link} **Allowed HTTP Methods:** :http:method:`get`, :http:method:`head`, :http:method:`options` @@ -105,6 +102,7 @@ @api_route(r'/origin/(?P[a-z]+)/url/(?P.+)/', 'api-1-origin') @api_doc('/origin/') +@format_docstring() def api_origin(request, origin_id=None, origin_type=None, origin_url=None): """ .. http:get:: /api/1/origin/(origin_id)/ @@ -121,10 +119,7 @@ ``deposit``) :>json string url: the origin canonical url - :reqheader Accept: the requested response content type, - either ``application/json`` (default) or ``application/yaml`` - :resheader Content-Type: this depends on :http:header:`Accept` header - of request + {common_headers} **Allowed HTTP Methods:** :http:method:`get`, :http:method:`head`, :http:method:`options` @@ -153,10 +148,7 @@ :>json string type: the type of software origin :>json string url: the origin canonical url - :reqheader Accept: the requested response content type, either - ``application/json`` (default) or ``application/yaml`` - :resheader Content-Type: this depends on :http:header:`Accept` header - of request + {common_headers} **Allowed HTTP Methods:** :http:method:`get`, :http:method:`head`, :http:method:`options` @@ -191,6 +183,7 @@ @api_route(r'/origin/search/(?P.+)/', 'api-1-origin-search') @api_doc('/origin/search/') +@format_docstring() def api_origin_search(request, url_pattern): """ .. http:get:: /api/1/origin/search/(url_pattern)/ @@ -214,10 +207,7 @@ :>jsonarr string type: the type of software origin :>jsonarr string url: the origin canonical url - :reqheader Accept: the requested response content type, - either ``application/json`` (default) or ``application/yaml`` - :resheader Content-Type: this depends on :http:header:`Accept` header - of request + {common_headers} **Allowed HTTP Methods:** :http:method:`get`, :http:method:`head`, :http:method:`options` @@ -263,6 +253,7 @@ @api_route(r'/origin/metadata-search/', 'api-1-origin-metadata-search') @api_doc('/origin/metadata-search/', noargs=True, need_params=True) +@format_docstring() def api_origin_metadata_search(request): """ .. http:get:: /api/1/origin/metadata-search/ @@ -284,10 +275,7 @@ metadata (the current HEAD or one of the former HEADs) :>jsonarr dict tool: the tool used to extract these metadata - :reqheader Accept: the requested response content type, - either ``application/json`` (default) or ``application/yaml`` - :resheader Content-Type: this depends on :http:header:`Accept` header - of request + {common_headers} **Allowed HTTP Methods:** :http:method:`get`, :http:method:`head`, :http:method:`options` @@ -316,6 +304,7 @@ @api_route(r'/origin/(?P[0-9]+)/visits/', 'api-1-origin-visits') @api_doc('/origin/visits/') +@format_docstring() def api_origin_visits(request, origin_id): """ .. http:get:: /api/1/origin/(origin_id)/visits/ @@ -330,12 +319,8 @@ :query int last_visit: visit to start listing from, for pagination purposes - :reqheader Accept: the requested response content type, - either ``application/json`` (default) or ``application/yaml`` - :resheader Content-Type: this depends on :http:header:`Accept` header - of request - :resheader Link: indicates that a subsequent result page is available - and contains the url pointing to it + {common_headers} + {resheader_link} :>jsonarr string date: ISO representation of the visit date (in UTC) :>jsonarr number id: the unique identifier of the origin @@ -416,6 +401,7 @@ @api_route(r'/origin/(?P[0-9]+)/visit/(?P[0-9]+)/', 'api-1-origin-visit') @api_doc('/origin/visit/') +@format_docstring() def api_origin_visit(request, origin_id, visit_id): """ .. http:get:: /api/1/origin/(origin_id)/visit/(visit_id)/ @@ -425,10 +411,7 @@ :param int origin_id: a software origin identifier :param int visit_id: a visit identifier - :reqheader Accept: the requested response content type, either - ``application/json`` (default) or ``application/yaml`` - :resheader Content-Type: this depends on :http:header:`Accept` - header of request + {common_headers} :>json string date: ISO representation of the visit date (in UTC) :>json number origin: the origin unique identifier @@ -466,6 +449,7 @@ @api_route(r'/origin/(?P[a-z]+)/url/(?P.+)' '/intrinsic-metadata', 'api-origin-intrinsic-metadata') @api_doc('/origin/intrinsic-metadata/') +@format_docstring() def api_origin_intrinsic_metadata(request, origin_type, origin_url): """ .. http:get:: /api/1/origin/(origin_type)/url/(origin_url)/intrinsic-metadata @@ -478,9 +462,7 @@ :>json string ???: intrinsic metadata field of the origin - :reqheader Accept: the requested response content type, - either ``application/json`` (default) or ``application/yaml`` - :resheader Content-Type: this depends on :http:header:`Accept` header of request + {common_headers} **Allowed HTTP Methods:** :http:method:`get`, :http:method:`head`, :http:method:`options` diff --git a/swh/web/api/views/origin_save.py b/swh/web/api/views/origin_save.py --- a/swh/web/api/views/origin_save.py +++ b/swh/web/api/views/origin_save.py @@ -5,7 +5,7 @@ from django.views.decorators.cache import never_cache -from swh.web.api.apidoc import api_doc +from swh.web.api.apidoc import api_doc, format_docstring from swh.web.api.apiurls import api_route from swh.web.common.origin_save import ( create_save_origin_request, get_save_origin_requests @@ -17,6 +17,7 @@ throttle_scope='swh_save_origin') @never_cache @api_doc('/origin/save/') +@format_docstring() def api_save_origin(request, origin_type, origin_url): """ .. http:get:: /api/1/origin/save/(origin_type)/url/(origin_url)/ @@ -55,10 +56,7 @@ (currently the supported types are ``git``, ``hg`` and ``svn``) :param string origin_url: the url of the origin to save - :reqheader Accept: the requested response content type, - either ``application/json`` (default) or ``application/yaml`` - :resheader Content-Type: this depends on :http:header:`Accept` - header of request + {common_headers} :>json string origin_url: the url of the origin to save :>json string origin_type: the type of the origin to save diff --git a/swh/web/api/views/person.py b/swh/web/api/views/person.py --- a/swh/web/api/views/person.py +++ b/swh/web/api/views/person.py @@ -4,13 +4,14 @@ # See top-level LICENSE file for more information from swh.web.common import service -from swh.web.api.apidoc import api_doc +from swh.web.api.apidoc import api_doc, format_docstring from swh.web.api.apiurls import api_route from swh.web.api.views.utils import api_lookup @api_route(r'/person/(?P[0-9]+)/', 'api-1-person') @api_doc('/person/') +@format_docstring() def api_person(request, person_id): """ .. http:get:: /api/1/person/(person_id)/ @@ -19,10 +20,7 @@ :param int person_id: a person identifier - :reqheader Accept: the requested response content type, - either ``application/json`` (default) or ``application/yaml`` - :resheader Content-Type: this depends on :http:header:`Accept` header - of request + {common_headers} :>json string email: the email of the person :>json string fullname: the full name of the person: combination of its diff --git a/swh/web/api/views/release.py b/swh/web/api/views/release.py --- a/swh/web/api/views/release.py +++ b/swh/web/api/views/release.py @@ -5,7 +5,7 @@ from swh.web.common import service from swh.web.api import utils -from swh.web.api.apidoc import api_doc +from swh.web.api.apidoc import api_doc, format_docstring from swh.web.api.apiurls import api_route from swh.web.api.views.utils import api_lookup @@ -13,6 +13,7 @@ @api_route(r'/release/(?P[0-9a-f]+)/', 'api-1-release', checksum_args=['sha1_git']) @api_doc('/release/') +@format_docstring() def api_release(request, sha1_git): """ .. http:get:: /api/1/release/(sha1_git)/ @@ -25,10 +26,7 @@ :param string sha1_git: hexadecimal representation of the release **sha1_git** identifier - :reqheader Accept: the requested response content type, - either ``application/json`` (default) or ``application/yaml`` - :resheader Content-Type: this depends on :http:header:`Accept` - header of request + {common_headers} :>json object author: information about the author of the release :>json string author_url: link to diff --git a/swh/web/api/views/revision.py b/swh/web/api/views/revision.py --- a/swh/web/api/views/revision.py +++ b/swh/web/api/views/revision.py @@ -114,9 +114,7 @@ pointed by the given branch should be looked up. The timestamp can be expressed either as an ISO date or as a Unix one (in UTC). Defaults to now. - :reqheader Accept: the requested response content type, - either ``application/json`` (default) or ``application/yaml`` - :resheader Content-Type: this depends on :http:header:`Accept` header of request + {common_headers} {return_revision_array} @@ -245,9 +243,7 @@ pointed by the given branch should be looked up. The timestamp can be expressed either as an ISO date or as a Unix one (in UTC). Defaults to now. - :reqheader Accept: the requested response content type, - either ``application/json`` (default) or ``application/yaml`` - :resheader Content-Type: this depends on :http:header:`Accept` header of request + {common_headers} {return_revision} @@ -287,10 +283,7 @@ :param string sha1_git: hexadecimal representation of the revision **sha1_git** identifier - :reqheader Accept: the requested response content type, - either ``application/json`` (default) or ``application/yaml`` - :resheader Content-Type: this depends on :http:header:`Accept` header - of request + {common_headers} {return_revision} @@ -332,6 +325,7 @@ @api_route(r'/revision/(?P[0-9a-f]+)/directory/(?P.+)/', 'api-1-revision-directory', checksum_args=['sha1_git']) @api_doc('/revision/directory/') +@format_docstring() def api_revision_directory(request, sha1_git, dir_path=None, with_data=False): @@ -347,9 +341,7 @@ :param string path: optional parameter to get information about the directory entry pointed by that relative path - :reqheader Accept: the requested response content type, - either ``application/json`` (default) or ``application/yaml`` - :resheader Content-Type: this depends on :http:header:`Accept` header of request + {common_headers} :>json array content: directory entries as returned by :http:get:`/api/1/directory/(sha1_git)/[(path)/]` :>json string path: path of directory from the revision root one @@ -392,11 +384,8 @@ If provided, revisions information will be added at the beginning of the returned list. :query int per_page: number of elements in the returned list, for pagination purpose - :reqheader Accept: the requested response content type, - either ``application/json`` (default) or ``application/yaml`` - :resheader Content-Type: this depends on :http:header:`Accept` header of request - :resheader Link: indicates that a subsequent result page is available and contains - the url pointing to it + {common_headers} + {resheader_link} {return_revision_array} diff --git a/swh/web/api/views/snapshot.py b/swh/web/api/views/snapshot.py --- a/swh/web/api/views/snapshot.py +++ b/swh/web/api/views/snapshot.py @@ -6,7 +6,7 @@ from swh.web.common import service from swh.web.common.utils import reverse from swh.web.config import get_config -from swh.web.api.apidoc import api_doc +from swh.web.api.apidoc import api_doc, format_docstring from swh.web.api import utils from swh.web.api.apiurls import api_route from swh.web.api.views.utils import api_lookup @@ -15,6 +15,7 @@ @api_route(r'/snapshot/(?P[0-9a-f]+)/', 'api-1-snapshot', checksum_args=['snapshot_id']) @api_doc('/snapshot/') +@format_docstring() def api_snapshot(request, snapshot_id): """ .. http:get:: /api/1/snapshot/(snapshot_id)/ @@ -45,12 +46,8 @@ ``directory``, ``revision``, ``release``, ``snapshot`` or ``alias``) - :reqheader Accept: the requested response content type, - either ``application/json`` (default) or ``application/yaml`` - :resheader Content-Type: this depends on :http:header:`Accept` header - of request - :resheader Link: indicates that a subsequent result page is available - and contains the url pointing to it + {common_headers} + {resheader_link} :>json object branches: object containing all branches associated to the snapshot,for each of them the associated target type and id are diff --git a/swh/web/api/views/stat.py b/swh/web/api/views/stat.py --- a/swh/web/api/views/stat.py +++ b/swh/web/api/views/stat.py @@ -4,12 +4,13 @@ # See top-level LICENSE file for more information from swh.web.common import service -from swh.web.api.apidoc import api_doc +from swh.web.api.apidoc import api_doc, format_docstring from swh.web.api.apiurls import api_route @api_route(r'/stat/counters/', 'api-1-stat-counters') @api_doc('/stat/counters/', noargs=True) +@format_docstring() def api_stats(request): """ .. http:get:: /api/1/stat/counters/ @@ -36,10 +37,7 @@ :>json number snapshot: current number of snapshot objects (aka set of named branches) in the archive - :reqheader Accept: the requested response content type, - either ``application/json`` (default) or ``application/yaml`` - :resheader Content-Type: this depends on - :http:header:`Accept` header of request + {common_headers} **Allowed HTTP Methods:** :http:method:`get`, :http:method:`head`, :http:method:`options` diff --git a/swh/web/api/views/vault.py b/swh/web/api/views/vault.py --- a/swh/web/api/views/vault.py +++ b/swh/web/api/views/vault.py @@ -9,7 +9,7 @@ from swh.model import hashutil from swh.web.common import service, query from swh.web.common.utils import reverse -from swh.web.api.apidoc import api_doc +from swh.web.api.apidoc import api_doc, format_docstring from swh.web.api.apiurls import api_route from swh.web.api.views.utils import api_lookup @@ -37,6 +37,7 @@ throttle_scope='swh_vault_cooking') @never_cache @api_doc('/vault/directory/') +@format_docstring() def api_vault_cook_directory(request, dir_id): """ .. http:get:: /api/1/vault/directory/(dir_id)/ @@ -61,10 +62,7 @@ :query string email: e-mail to notify when the archive is ready - :reqheader Accept: the requested response content type, - either ``application/json`` (default) or ``application/yaml`` - :resheader Content-Type: this depends on - :http:header:`Accept` header of request + {common_headers} :>json string fetch_url: the url from which to download the archive once it has been cooked @@ -135,6 +133,7 @@ throttle_scope='swh_vault_cooking') @never_cache @api_doc('/vault/revision/gitfast/') +@format_docstring() def api_vault_cook_revision_gitfast(request, rev_id): """ .. http:get:: /api/1/vault/revision/(rev_id)/gitfast/ @@ -161,10 +160,7 @@ :query string email: e-mail to notify when the gitfast archive is ready - :reqheader Accept: the requested response content type, - either ``application/json`` (default) or ``application/yaml`` - :resheader Content-Type: this depends on - :http:header:`Accept` header of request + {common_headers} :>json string fetch_url: the url from which to download the archive once it has been cooked