OpenAPI spec parsing: add custom templates w/ warning

dactyl-config.yml

@@ -2844,6 +2844,7 @@ pages:
 
         # API reference generator makes multiple files here
     -   openapi_specification: https://raw.githubusercontent.com/ripple/xrp-api/master/api-doc.yml
+        openapi_md_template_path: tool/openapi_templates_alpha/
         api_slug: xrp-api
         funnel: Docs
         doc_type: References

tool/openapi_templates_alpha/template-openapi_data_type.md

@@ -0,0 +1,64 @@
+# {{title}}
+
+{{description}}
+
+**Warning:** {{spec.info.title}} is early alpha software. API methods and data formats are likely to change frequently in ways that break backwards compatibility.
+
+{% if type is defined %}- **Type:** {{type|title}}
+{% elif oneOf is defined %}- **Possible Types:**
+{% for option in oneOf -%}
+{% if option.enum is defined %}
+    - One of the following {% if option.type is defined %}{{option.type|title}}s{% else %}values{% endif %}:
+{% for suboption in option.enum %}
+        - `{{suboption}}`
+{% endfor -%}
+{% else %}
+    - {{option.type|title}}
+{% endif -%}
+{% endfor -%}
+{% elif anyOf is defined %}- **Possible Types:**
+{% for option in anyOf -%}
+{% if option.enum is defined %}
+    - Any of the following {% if option.type is defined %}{{option.type|title}}s{% else %}values{% endif %}:
+{% for suboption in option.enum %}
+        - `{{suboption}}`
+{% endfor -%}
+{% else %}
+    - {{option.type|title}}
+{% endif -%}
+{% endfor -%}
+{% elif allOf is defined %}- **Possible Types:**
+{% for option in allOf -%}
+{% if option.enum is defined %}
+    - Must qualify as all of the following {% if option.type is defined %}{{option.type|title}}s{% else %}values{% endif %}:
+{% for suboption in option.enum %}
+        - `{{suboption}}`
+{% endfor -%}
+{% else %}
+    - {{option.type|title}}
+{% endif -%}
+{% endfor -%}
+{% endif -%}
+{% if enum is defined %}- **Possible Values:**
+{% for option in enum %}
+    - `{{option}}`
+{% endfor %}{% endif %}
+{% if pattern is defined %}- **Pattern:** `{{pattern}}`
+{% endif -%}
+{% if example is defined %}- **Example:** `{{example}}`
+{% endif -%}
+
+{% if properties is defined %}
+This type can contain the following fields:
+
+| Field | Type | Required? | Description |
+|-------|------|-----------|-------------|
+{%- for name,field in properties.items() %}
+| `{{name}}` | {{field.type|title}}{% if "items" in field.keys() and "title" in field["items"].keys() %} of [{{field["items"].title}}]({{type_link(field["items"].title)}}){% endif %} {% if field["title"] is defined %}([{{field.title}}]({{type_link(field.title)}})){% endif %} | {{"Required" if name in required else "Optional"}} | {{field.description}} |
+{%- endfor %}
+
+{% if additionalProperties is defined and additionalProperties == True %}This type MUST NOT contain any additional fields.{% endif %}
+
+{% elif type == "array" and items is defined %}
+Each member of the array is a ***TODO*** {{items}}
+{% endif %}

tool/openapi_templates_alpha/template-openapi_data_types_toc.md

@@ -0,0 +1,11 @@
+# {{api_title}} Data Types
+
+**Warning:** {{spec.info.title}} is early alpha software. API methods and data formats are likely to change frequently in ways that break backwards compatibility.
+
+The following data types are defined for this API:
+
+| Name | Type | Description |
+|------|------|-------------|
+{%- for key,schema in schemas %}
+| `{{schema.title}}` | {{schema.type|title}}{% if "items" in schema.keys() and "title" in schema["items"].keys() %} of [{{schema["items"].title}}]({{type_link(schema["items"].title)}}){% endif %} {% if schema["title"] is defined %}([{{schema.title}}]({{type_link(schema.title)}})){% endif %} | {% if schema.description is defined %}{{schema.description}}{% endif %} |
+{%- endfor %}

tool/openapi_templates_alpha/template-openapi_endpoint.md

@@ -0,0 +1,107 @@
+# {{summary}}
+
+{{description}}
+
+**Warning:** {{spec.info.title}} is early alpha software. API methods and data formats are likely to change frequently in ways that break backwards compatibility.
+
+## Request Format
+
+```
+{{method|upper}} {{path}}
+{%- if method in ["post","put","delete"] and requestBody is defined %}
+
+{{ x_example_request_body }}
+{% endif %}
+```
+
+{% if path_params|length %}
+This API method uses the following path parameters:
+
+| Field | Value | Required? | Description |
+|---|---|---|---|
+{%- for param in path_params %}
+| `{{param.name}}` | {% if param.schema is defined %}{% if param.schema.oneOf is defined %}(Varies){% else %}{{param.schema.type|title}}{% endif %} {% if param.schema["title"] is defined %}([{{param.schema.title}}]({{type_link(param.schema.title)}})){% endif %}{% else %}(Unspecified){% endif %} | {{"Required" if param.required else "Optional"}} | {{param.description}} |
+{%- endfor %}
+
+{% endif %}
+
+{% if query_params|length %}
+This API method uses the following query parameters:
+
+| Field | Value | Required? | Description |
+|---|---|---|---|
+{%- for param in query_params %}
+| `{{param.name}}` | {% if param.schema is defined %}{% if param.schema.oneOf is defined %}(Varies){% else %}{{param.schema.type|title}}{% if "items" in param.schema.keys() and "title" in param.schema["items"].keys() %} of [{{param.schema["items"].title}}]({{type_link(param.schema["items"].title)}}){% endif %}{% endif %} {% if param.schema["title"] is defined %}([{{param.schema.title}}]({{type_link(param.schema.title)}})){% endif %}{% else %}(Unspecified){% endif %} | {{"Required" if param.required else "Optional"}} | {{param.description}} |
+{%- endfor %}
+
+{% endif %}
+
+{% if requestBody is defined %}
+{{requestBody.description}}
+
+{% if requestBody.content is defined %}
+
+{% for mediatype,thisbody in requestBody.content.items() %}
+{% if thisbody.schema is defined %}
+**Media type:** {{mediatype|replace("*","\*")}}
+
+{% if thisbody.schema.title is defined %}
+Formatted as a [{{thisbody.schema.title}}]({{type_link(thisbody.schema.title)}})
+{% endif %}
+{% if thisbody.schema.properties is defined %}
+The request uses the following fields:
+
+| Field | Type | Required? | Description |
+|-------|------|-----------|-------------|
+{%- for name,field in thisbody.schema.properties.items() %}
+| `{{name}}` | {{field.type|title}}{% if "items" in field.keys() and "title" in field["items"].keys() %} of [{{field["items"].title}}]({{type_link(field["items"].title)}}){% endif %} {% if field["title"] is defined %}([{{field.title}}]({{type_link(field.title)}})){% endif %} | {{"Required" if name in required else "May be omitted"}} | {% if field.description is defined %}{{field.description}}{% endif %} |
+{%- endfor %}
+{% endif %}
+
+{% endif %}
+{% endfor %}
+{% endif %}
+{% endif %}
+
+## Response Formats
+
+{% for response_code, response in responses.items() %}
+### {{response_code}} {{HTTP_STATUS_CODES[response_code]}}
+
+{{ response.description}}
+
+{% if response.content is defined %}
+{% for mediatype,thisbody in response.content.items() %}
+{% if thisbody.schema is defined %}
+**Media type:** {{mediatype|replace("*","\*")}}
+
+{% if thisbody.schema.title is defined %}
+Formatted as a [{{thisbody.schema.title}}]({{type_link(thisbody.schema.title)}})
+{% endif %}
+{% if thisbody.schema.properties is defined %}
+The response uses the following fields:
+
+| Field | Type | Required? | Description |
+|-------|------|-----------|-------------|
+{%- for name,field in thisbody.schema.properties.items() %}
+| `{{name}}` | {{field.type|title}}{% if "items" in field.keys() and "title" in field["items"].keys() %} of [{{field["items"].title}}]({{type_link(field["items"].title)}}){% endif %} {% if field["title"] is defined %}([{{field.title}}]({{type_link(field.title)}})){% endif %} | {{"Required" if name in required else "May be omitted"}} | {% if field.description is defined %}{{field.description}}{% endif %} |
+{%- endfor %}
+{% endif %}{# TODO: handle allOf, etc. #}
+
+{% if thisbody.examples is defined and thisbody.examples|length > 0 %}
+#### Example Response(s)
+
+{% for body_name,body_sample in thisbody.examples %}
+_{{body_name}}_
+
+```
+{{body_sample|pprint}}
+```
+{% endfor %}
+{% endif %}
+
+{% endif %}
+{% endfor %}
+
+{% endif %}
+{% endfor %}

tool/openapi_templates_alpha/template-openapi_endpoint_tag_toc.md

@@ -0,0 +1,17 @@
+# {{info.title}} {{info.version}} {{tag.name|title}} Methods
+
+{{tag.description}}
+
+**Warning:** {{info.title}} is early alpha software. API methods and data formats are likely to change frequently in ways that break backwards compatibility.
+
+| Summary | Path |
+|:--------|:-----|
+{%- set reflinks = [] -%}
+{%- for path,method,endpoint in endpoints_by_tag(tag.name) %}
+{%- set _ = reflinks.append("["+endpoint.summary+"]: "+method_link(path, method, endpoint) ) %}
+| [{{endpoint.summary}}][] | [`{{method|upper}} {{path}}`][{{endpoint.summary}}] |
+{%- endfor %}
+
+{% for reflink in reflinks -%}
+{{reflink}}
+{% endfor %}

tool/openapi_templates_alpha/template-openapi_endpoint_toc.md

@@ -0,0 +1,51 @@
+# {{info.title}} {{info.version}} Methods
+
+{{info.description}}
+
+**Warning:** {{spec.info.title}} is early alpha software. API methods and data formats are likely to change frequently in ways that break backwards compatibility.
+
+{% if tags %}
+View API methods by category:
+
+{% for tag in tags %}
+- [{{tag.name|title}} Methods](#{{slugify(tag.name)|lower}}-methods)
+{% endfor %}
+{% endif %}
+
+{% for tag in tags %}
+{% if endpoints_by_tag(tag.name)|list|length %}
+## {{tag.name|title}} Methods
+
+{{tag.description}}
+
+| Summary | Path |
+|:--------|:-----|
+{%- set reflinks = [] -%}
+{%- for path,method,endpoint in endpoints_by_tag(tag.name) %}
+{%- set _ = reflinks.append("["+endpoint.summary+"]: "+method_link(path, method, endpoint) ) %}
+| [{{endpoint.summary}}][] | [`{{method|upper}} {{path}}`][{{endpoint.summary}}] |
+{%- endfor %}
+
+{% for reflink in reflinks -%}
+{{reflink}}
+{% endfor %}
+
+{% endif %}
+{% endfor %}
+
+{% if endpoints_by_tag("Uncategorized")|list|length %}
+## Uncategorized Methods
+
+| Name | Path | Summary |
+|:-----|:-----|:--------|
+{%- set reflinks = [] -%}
+{%- for path,method,endpoint in endpoints_by_tag("Uncategorized") %}
+{%- set _ = reflinks.append("["+endpoint.operationId+"]: "+method_link(path, method, endpoint) ) %}
+| [{{endpoint.operationId}}][] | [`{{method|upper}} {{path}}`][{{endpoint.operationId}}] | {{endpoint.summary}} |
+{%- endfor %}
+
+{% for reflink in reflinks -%}
+{{reflink}}
+{% endfor %}
+
+{% endif %}

tool/template-github-edit.html

@@ -1,4 +1,5 @@
 <div class="github-edit-wrap">
+  {% if target.github_forkurl is defined %}
     {% set have_edit_link = False %}
     {% if currentpage.md is defined %}
         {% if currentpage.md.startswith("http://") or
@@ -23,4 +24,5 @@
       {% set githuburl = target.github_forkurl %}
     {% endif %}
     <a href="{{githuburl}}" target="_blank" class="github-edit">Edit</a>
+  {% endif %}
 </div><!-- /.github-edit -->