From 26ebe3e68b413c3151b12885da713f9be556e80b Mon Sep 17 00:00:00 2001 From: Daniel Wagner-Hall Date: Tue, 8 Sep 2015 16:27:20 +0100 Subject: [PATCH 1/4] Add ability to refer to aliases of endpoints --- .../matrix_templates/templates/http-api.tmpl | 6 ++++++ templating/matrix_templates/units.py | 15 ++++++++++++++- 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/templating/matrix_templates/templates/http-api.tmpl b/templating/matrix_templates/templates/http-api.tmpl index 1384daab..a0b25924 100644 --- a/templating/matrix_templates/templates/http-api.tmpl +++ b/templating/matrix_templates/templates/http-api.tmpl @@ -1,5 +1,10 @@ ``{{endpoint.method}} {{endpoint.path}}`` {{(5 + (endpoint.path | length) + (endpoint.method | length)) * title_kind}} +{% if "alias_for_path" in endpoint -%} +``{{endpoint.path}}`` is an alias for `{{endpoint.alias_for_path}}`_. + +.. _`{{endpoint.alias_for_path}}`: #{{endpoint.alias_link}} +{% else -%} {{endpoint.desc | wrap(80)}} @@ -62,3 +67,4 @@ Example:: {{res["example"] | indent_block(2)}} {% endfor %} +{% endif -%} diff --git a/templating/matrix_templates/units.py b/templating/matrix_templates/units.py index c4ed8358..89b34bb1 100644 --- a/templating/matrix_templates/units.py +++ b/templating/matrix_templates/units.py @@ -105,11 +105,24 @@ class MatrixUnits(Units): for path in api["paths"]: for method in api["paths"][path]: single_api = api["paths"][path][method] + + full_path = api.get("basePath", "") + path + alias_for_path = single_api.get("x-alias-for-path", "") + alias_link = single_api.get("x-alias-link", "") + if alias_for_path: + endpoints.append({ + "method": method.upper(), + "path": full_path, + "alias_for_path": alias_for_path, + "alias_link": alias_link + }) + continue + endpoint = { "title": single_api.get("summary", ""), "desc": single_api.get("description", single_api.get("summary", "")), "method": method.upper(), - "path": api.get("basePath", "") + path, + "path": full_path, "requires_auth": "security" in single_api, "rate_limited": 429 in single_api.get("responses", {}), "req_params": [], From 90f5dc370b8e00b2f57ba98f0846b8bbbd7c1e12 Mon Sep 17 00:00:00 2001 From: Daniel Wagner-Hall Date: Tue, 8 Sep 2015 16:49:28 +0100 Subject: [PATCH 2/4] Populate aliases from canonical endpoint Swagger validates badly if you have endpoints without the full specification of things, so instead let's generate them the other way around. --- templating/matrix_templates/units.py | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/templating/matrix_templates/units.py b/templating/matrix_templates/units.py index 89b34bb1..8e991fa8 100644 --- a/templating/matrix_templates/units.py +++ b/templating/matrix_templates/units.py @@ -105,19 +105,7 @@ class MatrixUnits(Units): for path in api["paths"]: for method in api["paths"][path]: single_api = api["paths"][path][method] - full_path = api.get("basePath", "") + path - alias_for_path = single_api.get("x-alias-for-path", "") - alias_link = single_api.get("x-alias-link", "") - if alias_for_path: - endpoints.append({ - "method": method.upper(), - "path": full_path, - "alias_for_path": alias_for_path, - "alias_link": alias_link - }) - continue - endpoint = { "title": single_api.get("summary", ""), "desc": single_api.get("description", single_api.get("summary", "")), @@ -260,6 +248,16 @@ class MatrixUnits(Units): endpoints.append(endpoint) + for alias in single_api.get("x-aliases", []): + canonical_alias_link = single_api.get("x-alias-link") + alias_link = single_api.get("x-alias-link", "") + endpoints.append({ + "method": method.upper(), + "path": alias, + "alias_for_path": full_path, + "alias_link": alias_link + }) + return { "base": api.get("basePath"), "group": group_name, From 64cfc00f5055959f4a67d51d29711c7f4b746e97 Mon Sep 17 00:00:00 2001 From: Daniel Wagner-Hall Date: Tue, 8 Sep 2015 17:07:52 +0100 Subject: [PATCH 3/4] Remove unused fluff --- templating/matrix_templates/units.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/templating/matrix_templates/units.py b/templating/matrix_templates/units.py index 8e991fa8..24fb3767 100644 --- a/templating/matrix_templates/units.py +++ b/templating/matrix_templates/units.py @@ -249,8 +249,7 @@ class MatrixUnits(Units): endpoints.append(endpoint) for alias in single_api.get("x-aliases", []): - canonical_alias_link = single_api.get("x-alias-link") - alias_link = single_api.get("x-alias-link", "") + alias_link = single_api.get("x-alias-link") endpoints.append({ "method": method.upper(), "path": alias, From d399e5b93bac92bcbe82a79e6aecb90a92f38fe7 Mon Sep 17 00:00:00 2001 From: Daniel Wagner-Hall Date: Wed, 9 Sep 2015 13:16:46 +0100 Subject: [PATCH 4/4] Use an alias object rather than flat fields --- templating/matrix_templates/units.py | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/templating/matrix_templates/units.py b/templating/matrix_templates/units.py index 24fb3767..d8cc213d 100644 --- a/templating/matrix_templates/units.py +++ b/templating/matrix_templates/units.py @@ -248,14 +248,16 @@ class MatrixUnits(Units): endpoints.append(endpoint) - for alias in single_api.get("x-aliases", []): - alias_link = single_api.get("x-alias-link") - endpoints.append({ - "method": method.upper(), - "path": alias, - "alias_for_path": full_path, - "alias_link": alias_link - }) + aliases = single_api.get("x-alias", None) + if aliases: + alias_link = aliases["canonical-link"] + for alias in aliases["aliases"]: + endpoints.append({ + "method": method.upper(), + "path": alias, + "alias_for_path": full_path, + "alias_link": alias_link + }) return { "base": api.get("basePath"),