mess with template

This commit is contained in:
Devin Howard 2016-10-12 11:08:09 +08:00
parent 9c55883eeb
commit 94092ca716
8 changed files with 602 additions and 3 deletions

View file

@ -2,8 +2,13 @@
# Note: you need to run `npm install` before using this script or raml2html won't be installed
OLD_DIR=$(pwd)
cd $(dirname $0)/..
if [[ ! -x ./node_modules/.bin/raml2html ]]; then
npm install
fi
./node_modules/.bin/raml2html -i ./doc/api/api.raml -o ./public/api/index.html
./node_modules/.bin/raml2html -i ./doc/api/api.raml -o ./public/api/index.html -t doc/api/templates/template.nunjucks
cd $OLD_DIR

View file

@ -13,7 +13,9 @@ documentation:
securitySchemes:
oauth_2_0: !include securitySchemes/oauth_2_0.raml
securedBy: [ null, cookie, token, oauth_2_0 ]
token: !include securitySchemes/token.raml
cookie: !include securitySchemes/cookie.raml
securedBy: [ token, cookie, oauth_2_0 ]
traits:
pageable: !include traits/pageable.raml

View file

@ -0,0 +1,3 @@
description: Cookie-based authentication
type: x-cookie
displayName: Cookie

View file

@ -1,4 +1,4 @@
description: !include ../pages/oauth_tutorial.md
description: Secured by OAuth 2.0
type: OAuth 2.0
settings:
authorizationUri: https://metamaps.cc/api/v2/oauth/authorize

View file

@ -0,0 +1,3 @@
description: Token-based authenticationSecured by OAuth 2.0
type: x-token
displayName: Token-based auth

View file

@ -0,0 +1,61 @@
<li>
{% if item.displayName %}
<strong>{{ item.displayName }}</strong>:
{% else %}
<strong>{{ item.key }}</strong>:
{% endif %}
{% if not item.structuredValue %}
<em>
{%- if item.required -%}required {% endif -%}
(
{%- if item.enum -%}
{%- if item.enum.length === 1 -%}
{{ item.enum.join(', ') }}
{%- else -%}
one of {{ item.enum.join(', ') }}
{%- endif -%}
{%- else -%}
{{ item.type }}
{%- endif -%}
{%- if item.default or item.default == 0 or item.default == false %} - default: {{ item.default }}{%- endif -%}
{%- if item.repeat %} - repeat: {{ item.repeat }}{%- endif -%}
{%- if item.type == 'string' -%}
{%- if item.minLength or item.minLength == 0 %} - minLength: {{ item.minLength }}{%- endif -%}
{%- if item.maxLength or item.maxLength == 0 %} - maxLength: {{ item.maxLength }}{%- endif -%}
{%- else -%}
{%- if item.minimum or item.minimum == 0 %} - minimum: {{ item.minimum }}{%- endif -%}
{%- if item.maximum or item.maximum == 0 %} - maximum: {{ item.maximum }}{%- endif -%}
{%- endif -%}
{%- if item.pattern %} - pattern: {{ item.pattern }}{%- endif -%}
)
</em>
{% endif %}
{% markdown %}
{{ item.description }}
{% endmarkdown %}
{#
{% if item.type %}
<p><strong>Type</strong>:</p>
<pre><code>{{ item.type | escape }}</code></pre>
{% endif %}
#}
{% if item.examples.length %}
<p><strong>Examples</strong>:</p>
{% for example in item.examples %}
{% if item.type == 'string' %}
<pre>{{ example | escape }}</pre>
{% else %}
<pre><code>{{ example | escape }}</code></pre>
{% endif %}
{% endfor %}
{% endif %}
{% if item.structuredValue %}
<pre><code>{{ item.structuredValue | dump }}</code></pre>
{% endif %}
</li>

View file

@ -0,0 +1,293 @@
{% if (resource.methods or (resource.description and resource.parentUrl)) %}
<div class="panel panel-white">
<div class="panel-heading">
<h4 class="panel-title">
<a class="collapsed" data-toggle="collapse" href="#panel_{{ resource.uniqueId }}">
<span class="parent">{{ resource.parentUrl }}</span>{{ resource.relativeUri }}
</a>
<span class="methods">
{% for method in resource.methods %}
<a href="#{{ resource.uniqueId }}_{{ method.method }}"><!-- modal shown by hashchange event -->
<span class="badge badge_{{ method.method }}">{{ method.method }}{% if method.securedBy.length %} <span class="glyphicon glyphicon-lock" title="Authentication required"></span>{% endif %}</span>
</a>
{% endfor %}
</span>
</h4>
</div>
<div id="panel_{{ resource.uniqueId }}" class="panel-collapse collapse">
<div class="panel-body">
{% if resource.parentUrl %}
{% if resource.description %}
<div class="resource-description">
{% markdown %}
{{ resource.description }}
{% endmarkdown %}
</div>
{% endif %}
{% endif %}
<div class="list-group">
{% for method in resource.methods %}
<div onclick="window.location.href = '#{{ resource.uniqueId }}_{{ method.method }}'" class="list-group-item">
<span class="badge badge_{{ method.method }}">{{ method.method }}{% if method.securedBy.length %} <span class="glyphicon glyphicon-lock" title="Authentication required"></span>{% endif %}</span>
<div class="method_description">
{% markdown %}
{{ method.description}}
{% endmarkdown %}
</div>
<div class="clearfix"></div>
</div>
{% endfor %}
</div>
</div>
</div>
{% for method in resource.methods %}
<div class="modal fade" tabindex="0" id="{{ resource.uniqueId }}_{{ method.method }}">
<div class="modal-dialog">
<div class="modal-content">
<div class="modal-header">
<button type="button" class="close" data-dismiss="modal" aria-hidden="true">&times;</button>
<h4 class="modal-title" id="myModalLabel">
<span class="badge badge_{{ method.method }}">{{ method.method }}{% if method.securedBy.length %} <span class="glyphicon glyphicon-lock" title="Authentication required"></span>{% endif %}</span>
<span class="parent">{{ resource.parentUrl }}</span>{{ resource.relativeUri }}
</h4>
</div>
<div class="modal-body">
{% if method.description %}
<div class="alert alert-info">
{% markdown %}
{{ method.description}}
{% endmarkdown %}
</div>
{% endif %}
{% if method.securedBy.length %}
{% for securedBy in method.securedBy %}
{% if securedBy %}
<div class="alert alert-warning">
{% set securedByScopes = renderSecuredBy(securedBy) %}
<span class="glyphicon glyphicon-lock" title="Authentication required"></span> Secured by {{ securedByScopes }}
{% set securityScheme = securitySchemes[securedBy] %}
{% if securityScheme.description %}
{% markdown %}
{{ securityScheme.description }}
{% endmarkdown %}
{% endif %}
</div>
{% endif %}
{% endfor %}
{% endif %}
<!-- Nav tabs -->
<ul class="nav nav-tabs">
{% if method.allUriParameters.length or method.queryString or method.queryParameters or method.headers or method.body %}
<li class="active">
<a href="#{{ resource.uniqueId }}_{{ method.method }}_request" data-toggle="tab">Request</a>
</li>
{% endif %}
{% if method.responses %}
<li{%
if not method.allUriParameters.length and not method.queryParameters
and not method.queryString
and not method.headers and not method.body
%} class="active"{%
endif
%}>
<a href="#{{ resource.uniqueId }}_{{ method.method }}_response" data-toggle="tab">Response</a>
</li>
{% endif %}
{% if method.securedBy.length %}
<li>
<a href="#{{ resource.uniqueId }}_{{ method.method }}_securedby" data-toggle="tab">Security</a>
</li>
{% endif %}
</ul>
<!-- Tab panes -->
<div class="tab-content">
{% if method.allUriParameters.length or method.queryString or method.queryParameters or method.headers or method.body %}
<div class="tab-pane active" id="{{ resource.uniqueId }}_{{ method.method }}_request">
{% if resource.allUriParameters.length %}
<h3>URI Parameters</h3>
<ul>
{% for item in resource.allUriParameters %}
{% include "./item.nunjucks" %}
{% endfor %}
</ul>
{% endif %}
{% if method.annotations.length %}
<h3>Annotations</h3>
<ul>
{% for item in method.annotations %}
{% include "./item.nunjucks" %}
{% endfor %}
</ul>
{% endif %}
{% if method.headers.length %}
<h3>Headers</h3>
<ul>
{% for item in method.headers %}
{% include "./item.nunjucks" %}
{% endfor %}
</ul>
{% endif %}
{% if method.queryString and method.queryString.properties.length %}
<h3>Query String</h3>
<ul>
{% for item in method.queryString.properties %}
{% include "./item.nunjucks" %}
{% endfor %}
</ul>
{% endif %}
{% if method.queryParameters.length %}
<h3>Query Parameters</h3>
<ul>
{% for item in method.queryParameters %}
{% include "./item.nunjucks" %}
{% endfor %}
</ul>
{% endif %}
{% if method.body %}
<h3>Body</h3>
{% for b in method.body %}
<p><strong>Type: {{ b.key }}</strong></p>
{#
{% if b.type %}
<p><strong>Type</strong>:</p>
<pre><code>{{ b.type | escape }}</code></pre>
{% endif %}
#}
{% if b.properties.length %}
<strong>Properties</strong>
<ul>
{% for item in b.properties %}
{% include "./item.nunjucks" %}
{% endfor %}
</ul>
{% endif %}
{% if b.examples.length %}
<p><strong>Examples</strong>:</p>
{% for example in b.examples %}
<pre><code>{{ example | escape }}</code></pre>
{% endfor %}
{% endif %}
{% endfor %}
{% endif %}
</div>
{% endif %}
{% if method.responses %}
<div class="tab-pane{%
if not method.allUriParameters.length and not method.queryParameters.length
and not method.queryString
and not method.headers.length and not method.body.length
%} active{%
endif
%}" id="{{ resource.uniqueId }}_{{ method.method }}_response">
{% for response in method.responses %}
<h2>HTTP status code <a href="http://httpstatus.es/{{ response.code }}" target="_blank">{{ response.code }}</a></h2>
{% markdown %}
{{ response.description}}
{% endmarkdown %}
{% if response.headers.length %}
<h3>Headers</h3>
<ul>
{% for item in response.headers %}
{% include "./item.nunjucks" %}
{% endfor %}
</ul>
{% endif %}
{% if response.body.length %}
<h3>Body</h3>
{% for b in response.body %}
<p><strong>Type: {{ b.key }}</strong></p>
{#
{% if b.type %}
<p><strong>Type</strong>:</p>
<pre><code>{{ b.type | escape }}</code></pre>
{% endif %}
#}
{% if b.properties.length %}
<strong>Properties</strong>
<ul>
{% for item in b.properties %}
{% include "./item.nunjucks" %}
{% endfor %}
</ul>
{% endif %}
{% if b.examples.length %}
<p><strong>Examples</strong>:</p>
{% for example in b.examples %}
<pre><code>{{ example | escape }}</code></pre>
{% endfor %}
{% endif %}
{% endfor %}
{% endif %}
{% endfor %}
</div>
{% endif %}
{% if method.securedBy.length %}
<div class="tab-pane" id="{{ resource.uniqueId }}_{{ method.method }}_securedby">
{% for securedBy in method.securedBy %}
{% set securityScheme = securitySchemes[securedBy] %}
<h1>Secured by {{ securedBy }}</h1>
{% if securityScheme.describedBy.headers.length %}
<h3>Headers</h3>
<ul>
{% for item in securityScheme.describedBy.headers %}
{% include "./item.nunjucks" %}
{% endfor %}
</ul>
{% endif %}
{% for response in securityScheme.describedBy.responses.length %}
<h2>HTTP status code <a href="http://httpstatus.es/{{ response.code }}" target="_blank">{{ response.code }}</a></h2>
{% markdown %}
{{ response.description}}
{% endmarkdown %}
{% if response.headers.length %}
<h3>Headers</h3>
<ul>
{% for item in response.headers %}
{% include "./item.nunjucks" %}
{% endfor %}
</ul>
{% endif %}
{% endfor %}
{% endfor %}
</div>
{% endif %}
</div>
</div>
</div>
</div>
</div>
{% endfor %}
</div>
{% endif %}
{% for resource in resource.resources %}
{% include "./resource.nunjucks" %}
{% endfor %}

View file

@ -0,0 +1,232 @@
<!DOCTYPE HTML>
<html>
<head>
<title>{{ title }} API documentation</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="generator" content="https://github.com/raml2html/raml2html {{ config.raml2HtmlVersion }}">
<link rel="stylesheet" href="https://netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.3.0/styles/default.min.css">
<script type="text/javascript" src="https://code.jquery.com/jquery-1.11.0.min.js"></script>
<script type="text/javascript" src="https://netdna.bootstrapcdn.com/bootstrap/3.1.1/js/bootstrap.min.js"></script>
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.3.0/highlight.min.js"></script>
<script type="text/javascript">
$(document).ready(function() {
$('.page-header pre code, .top-resource-description pre code, .modal-body pre code').each(function(i, block) {
hljs.highlightBlock(block);
});
$('[data-toggle]').click(function() {
var selector = $(this).data('target') + ' pre code';
$(selector).each(function(i, block) {
hljs.highlightBlock(block);
});
});
// open modal on hashes like #_action_get
$(window).bind('hashchange', function(e) {
var anchor_id = document.location.hash.substr(1); //strip #
var element = $('#' + anchor_id);
// do we have such element + is it a modal? --> show it
if (element.length && element.hasClass('modal')) {
element.modal('show');
}
});
// execute hashchange on first page load
$(window).trigger('hashchange');
// remove url fragment on modal hide
$('.modal').on('hidden.bs.modal', function() {
try {
if (history && history.replaceState) {
history.replaceState({}, '', '#');
}
} catch(e) {}
});
});
</script>
<style>
.hljs {
background: transparent;
}
.parent {
color: #999;
}
.list-group-item > .badge {
float: none;
margin-right: 6px;
}
.panel-title > .methods {
float: right;
}
.badge {
border-radius: 0;
text-transform: uppercase;
width: 70px;
font-weight: normal;
color: #f3f3f6;
line-height: normal;
}
.badge_get {
background-color: #63a8e2;
}
.badge_post {
background-color: #6cbd7d;
}
.badge_put {
background-color: #22bac4;
}
.badge_delete {
background-color: #d26460;
}
.badge_patch {
background-color: #ccc444;
}
.list-group, .panel-group {
margin-bottom: 0;
}
.panel-group .panel+.panel-white {
margin-top: 0;
}
.panel-group .panel-white {
border-bottom: 1px solid #F5F5F5;
border-radius: 0;
}
.panel-white:last-child {
border-bottom-color: white;
-webkit-box-shadow: none;
box-shadow: none;
}
.panel-white .panel-heading {
background: white;
}
.tab-pane ul {
padding-left: 2em;
}
.tab-pane h1 {
font-size: 1.3em;
}
.tab-pane h2 {
font-size: 1.2em;
padding-bottom: 4px;
border-bottom: 1px solid #ddd;
}
.tab-pane h3 {
font-size: 1.1em;
}
.tab-content {
border-left: 1px solid #ddd;
border-right: 1px solid #ddd;
border-bottom: 1px solid #ddd;
padding: 10px;
}
#sidebar {
margin-top: 30px;
padding-right: 5px;
overflow: auto;
height: 90%;
}
.top-resource-description {
border-bottom: 1px solid #ddd;
background: #fcfcfc;
padding: 15px 15px 0 15px;
margin: -15px -15px 10px -15px;
}
.resource-description {
border-bottom: 1px solid #fcfcfc;
background: #fcfcfc;
padding: 15px 15px 0 15px;
margin: -15px -15px 10px -15px;
}
.resource-description p:last-child {
margin: 0;
}
.list-group .badge {
float: left;
}
.method_description {
margin-left: 85px;
}
.method_description p:last-child {
margin: 0;
}
.list-group-item {
cursor: pointer;
}
.list-group-item:hover {
background-color: #f5f5f5;
}
pre code {
overflow: auto;
word-wrap: normal;
white-space: pre;
}
</style>
</head>
<body data-spy="scroll" data-target="#sidebar">
<div class="container">
<div class="row">
<div class="col-md-9" role="main">
<div class="page-header">
<h1>{{ title }} API documentation{% if version %} <small>version {{ version }}</small>{% endif %}</h1>
<p>{{ baseUri }}</p>
{% if baseUriParameters %}
<ul>
{% for item in baseUriParameters %}
{% include "./item.nunjucks" %}
{% endfor %}
</ul>
{% endif %}
</div>
{% for resource in resources %}
<div class="panel panel-default">
<div class="panel-heading">
<h3 id="{{ resource.uniqueId }}" class="panel-title">{% if resource.displayName %}{{ resource.displayName}}{% else %}{{ resource.relativeUri }}{% endif %}</h3>
</div>
<div class="panel-body">
{% if resource.description %}
<div class="top-resource-description">
{% markdown %}
{{ resource.description }}
{% endmarkdown %}
</div>
{% endif %}
<div class="panel-group">
{% include "./resource.nunjucks" %}
</div>
</div>
</div>
{% endfor %}
{% for chapter in documentation %}
<h3 id="{{ chapter.uniqueId }}"><a href="#{{ chapter.uniqueId }}">{{ chapter.title }}</a></h3>
{% markdown %}
{{ chapter.content }}
{% endmarkdown %}
{% endfor %}
</div>
<div class="col-md-3">
<div id="sidebar" class="hidden-print affix" role="complementary">
<ul class="nav nav-pills nav-stacked">
{% for resource in resources %}
<li><a href="#{{ resource.uniqueId}}">{% if resource.displayName %}{{ resource.displayName}}{% else %}{{ resource.relativeUri }}{% endif %}</a></li>
{% endfor %}
</ul>
</div>
</div>
</div>
</div>
</body>
</html>