From 30e35f827663004655116836491bcd8e266c9826 Mon Sep 17 00:00:00 2001 From: hermannsblum Date: Tue, 21 Apr 2015 11:28:31 +0200 Subject: [PATCH 1/4] add parsing of url_map to list all endpoints --- eve_docs/config.py | 33 ++++++++++++++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/eve_docs/config.py b/eve_docs/config.py index 16f83c2..d71c8c4 100644 --- a/eve_docs/config.py +++ b/eve_docs/config.py @@ -3,6 +3,7 @@ from .labels import LABELS import re + def get_cfg(): cfg = {} base = home_link()['href'] @@ -15,15 +16,45 @@ def get_cfg(): cfg['domains'] = {} cfg['server_name'] = capp.config['SERVER_NAME'] cfg['api_name'] = capp.config.get('API_NAME', 'API') + cfg['domains'] = parse_map(capp.url_map) + domains = {} for domain, resource in list(capp.config['DOMAIN'].items()): if resource['item_methods'] or resource['resource_methods']: # hide the shadow collection for document versioning if 'VERSIONS' not in capp.config or not \ domain.endswith(capp.config['VERSIONS']): - cfg['domains'][domain] = paths(domain, resource) + domains[domain] = paths(domain, resource) + cfg['domains'].update(domains) return cfg +def parse_map(url_map): + """ + will extract information out of the url_map and provide them in a dict-form + :param url_map: an url_map in the format like app.url_map from eve + :returns: empty dict if url-endpoints with methods + """ + ret = {} + for rule in url_map.iter_rules(): + line = str(rule) + # first part if the rule specifies the endpoint + # between the first two '/' is the resource + resource = line.split("/")[1] + # the endpoint is described by a regex, but we want only the name + path = re.sub(r'<(?:[^>]+:)?([^>]+)>', '{\\1}', line) + if resource not in ret: + # this is the first path of this resource, create dict-entry + ret[resource] = {} + # add path to dict + ret[resource][path] = {} + for method in rule.methods: + if method in ['GET', 'POST', 'PATCH', 'PUT', 'DELETE']: + # we only display these methods, other HTTP-Methods don't need + # documentation + ret[resource][path][method] = {} + return ret + + def identifier(resource): name = resource['item_lookup_field'] ret = { From d72f56eed22ab880a5aefea606575cda07bd59f6 Mon Sep 17 00:00:00 2001 From: hermannsblum Date: Tue, 21 Apr 2015 14:51:04 +0200 Subject: [PATCH 2/4] documentation --- eve_docs/config.py | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/eve_docs/config.py b/eve_docs/config.py index d71c8c4..560eb93 100644 --- a/eve_docs/config.py +++ b/eve_docs/config.py @@ -5,6 +5,18 @@ def get_cfg(): + """ + Will get all necessary data out of the eve-app. + It reads 'SERVER_NAME', 'API_NAME', and'DOMAIN' out of app.config as well + as app.url_map + + The Hirarchy of Information is: + 1. list all endpoints from url_map + 2. update with data out of DOMAIN + + :returns: dict with 'base', 'server_name', 'api_name', 'domains' for + template + """ cfg = {} base = home_link()['href'] if '://' not in base: @@ -16,7 +28,9 @@ def get_cfg(): cfg['domains'] = {} cfg['server_name'] = capp.config['SERVER_NAME'] cfg['api_name'] = capp.config.get('API_NAME', 'API') + # 1. parse rules from url_map cfg['domains'] = parse_map(capp.url_map) + # 2. Load schemas and paths from the config and update cfg domains = {} for domain, resource in list(capp.config['DOMAIN'].items()): if resource['item_methods'] or resource['resource_methods']: From 53e52c2a42a51c7923189e4060f71590c616b5b0 Mon Sep 17 00:00:00 2001 From: hermannsblum Date: Tue, 21 Apr 2015 14:55:37 +0200 Subject: [PATCH 3/4] more documentation in config.py --- eve_docs/config.py | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/eve_docs/config.py b/eve_docs/config.py index 560eb93..69d992c 100644 --- a/eve_docs/config.py +++ b/eve_docs/config.py @@ -80,6 +80,12 @@ def identifier(resource): def schema(resource, field=None): + """extracts the detailed cerberus-schema of this endpoint + :param resource: the resource of the endpoint + :param field: the field for which the schema will be returned. + If no field specified, return a dict for all fields of the endpoint + :returns: schema as dict + """ ret = [] if field is not None: params = {field: resource['schema'][field]} @@ -111,6 +117,12 @@ def schema(resource, field=None): def paths(domain, resource): + """returns the documentation of all endpoints of a domain for which we have + descriptions in the config + :param domain: the domain of the endpoints + :param resource: the resource-subdict of config['DOMAIN'] + :returns: dict with paths and their documentation (methods, fields) + """ ret = {} path = '/{0}'.format(resource.get('url', domain)) path = re.sub(r'<(?:[^>]+:)?([^>]+)>', '{\\1}', path) @@ -131,6 +143,13 @@ def paths(domain, resource): def methods(domain, resource, pathtype, param=None): + """extracts mathods and descriptions of a sepcified path + :param domain: the domain of the endpoint + :param resource: the resource-subdict of config['DOMAIN'] + :param pathtype: String from ('item', 'resource') + :param param: + :returns: dict of methods and their documentation (fields) + """ ret = {} if pathtype == 'additional_lookup': method = 'GET' @@ -159,6 +178,12 @@ def pathparam(param): def get_label(domain, pathtype, method): + """a description of what the method does (e.g. PATCH will upadate an item) + :param domain: the domain of the endpoint + :param pathtype: String from ('item', 'resource') + :param method: the method for this label + :returns: description as a string + """ verb = LABELS[method] if method == 'POST' or pathtype != 'resource': noun = capp.config['DOMAIN'][domain]['item_title'] From 1468075e60f64f5b1829005320b2cd05c7b0430c Mon Sep 17 00:00:00 2001 From: hermannsblum Date: Tue, 21 Apr 2015 14:57:17 +0200 Subject: [PATCH 4/4] documentation --- eve_docs/config.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/eve_docs/config.py b/eve_docs/config.py index 69d992c..3578a43 100644 --- a/eve_docs/config.py +++ b/eve_docs/config.py @@ -12,7 +12,7 @@ def get_cfg(): The Hirarchy of Information is: 1. list all endpoints from url_map - 2. update with data out of DOMAIN + 2. update with data out of DOMAIN (specific fields) :returns: dict with 'base', 'server_name', 'api_name', 'domains' for template