From 7eae8deacbaed64394dd3071274f46cd1632da20 Mon Sep 17 00:00:00 2001
From: Devin Howard <devin@callysto.com>
Date: Thu, 13 Oct 2016 01:54:43 +0800
Subject: [PATCH] revamp HTML template a bit for api docs (#757)

* my_tokens endpoint moved to normal index

* remove secured_by from metacodes/users

* ch ch ch changes

* mess with template

* fix securedBy

* convenience open

* gross authentication notes at the top of every endpoint

* better ordering

* move login tutorials into security tab

* oauth tutorial

* getting closer

* remove unneeded Endpoints header

* ok looks OK
---
 .env.swp                                    | Bin 0 -> 12288 bytes
 app/controllers/api/v2/tokens_controller.rb |   6 -
 bin/build-apidocs.sh                        |  10 +-
 config/routes.rb                            |   4 +-
 doc/api/api.raml                            |   6 +-
 doc/api/apis/metacodes.raml                 |   2 +
 doc/api/apis/tokens.raml                    |  17 +-
 doc/api/apis/users.raml                     |  18 +-
 doc/api/pages/cookie_tutorial.md            |   3 +
 doc/api/pages/getting-started.md            |  86 +-----
 doc/api/pages/oauth_2_0_tutorial.md         |  41 +++
 doc/api/pages/token_tutorial.md             |  25 ++
 doc/api/securitySchemes/cookie.raml         |   3 +
 doc/api/securitySchemes/oauth_2_0.raml      |   3 +-
 doc/api/securitySchemes/token.raml          |   3 +
 doc/api/templates/item.nunjucks             |  61 ++++
 doc/api/templates/resource.nunjucks         | 314 ++++++++++++++++++++
 doc/api/templates/template.nunjucks         | 232 +++++++++++++++
 18 files changed, 718 insertions(+), 116 deletions(-)
 create mode 100644 .env.swp
 create mode 100644 doc/api/pages/cookie_tutorial.md
 create mode 100644 doc/api/pages/oauth_2_0_tutorial.md
 create mode 100644 doc/api/pages/token_tutorial.md
 create mode 100644 doc/api/securitySchemes/cookie.raml
 create mode 100644 doc/api/securitySchemes/token.raml
 create mode 100644 doc/api/templates/item.nunjucks
 create mode 100644 doc/api/templates/resource.nunjucks
 create mode 100644 doc/api/templates/template.nunjucks

diff --git a/.env.swp b/.env.swp
new file mode 100644
index 0000000000000000000000000000000000000000..e737a79b5a0d3866f6b3955a4495bd58f83cdc9c
GIT binary patch
literal 12288
zcmeI2&yU+g6vthJprw>naIc2ukX_Ma$G`0r2C|9U4V%QPIN7CiD>ELCH_>|SU^{IW
zDv;VDapTwvN5qXA5>opQ@CP6+2!VP++&FXLIh&;WLo6WmK&7$tjpH}(y?OKTjI*1J
zk2jiaq*oOIjtheDrTfF?#Z!Xt?el^#_Q!EPE*efgXcEUsnv9Yt8E2JUmXlpF%7P@P
zv?7^`s)+I=!6*9(mu@BLPBtQxEmc{3^W@yTl@s6uo)&>~f-H%+$X2@aI(qHZ{?kg#
z^Kb&304Kl+Z~~kFC%_4C0-V4zKp-ET5<Z1GpPSY?`5pk?!&d;4V|Jci@)IY(32*|O
z04Kl+Z~~kFC%_4C0-OLRzzIBq1V|tV4_*|6d#9mz`2BzO|NrCjg77`)8_)yL$Dofu
z70~am2*M-KL(oOg{c{ixQbA`yXFz|vEC@e>z5{&?`U>;~=r)Lf)<Gu70R4GZ5Pk;z
z1bPH|2>Kk<1ziTc0Q%)6*pmSI4D<m=2b~7}dIs#Ed!W0ZHs}KAJm@zV(|u4ew!6jn
z_`wNq0-OLRzzJ{y{~H3O5<+M@Wg}Ecn^`hIm34G!;q5mqyR)&luvHCNP6t~HcebuC
zR<GA8?|V1is4i?R-r2gbcnRH^MkWw5Z7hsglIEx~MsJ~<?T(O8LSd33g2wUiLzJWe
zOId)TVV0vLM6e4H-6UzY4Ev%E*YclADT2dc9H4x_5Y&$7I89lcM|)@(qjAQHQ_)67
zBe)#K+h`fVpF_7tMX}xf$~Et5-E&%vcCFQN>RzkaZuY#ZU1zhm>RqYTdrsF9VW;Ll
z1hi}KS(+hfrU_fUPWH8ANyVmOh)4ZStUxnPbf5HZVpSDY`6Nf^+%RMXYe$_{?b>>Q
z!C86NuJ@)G{(k%u_bDal+jCn^&$V<#)sGGTpzAy#K33(#?Mm0Sr@2(sl=NeRo_IAo
zaEtbP6b((0jt!>gtl1q)2^HDEAvK9)sCpoV7#kR?L}tFBnbNV`y?)2GFe+s%M|pz8
z;)TV;j~KdIhbf)qFjY}H_V>^>Nqw@-5KW?p(R`T1D9guTC=`=^di&j0t-j{j9dFZK
zS#_K>uitG!YYAlxrYpNm*=Q0NC;2cOQc_%GMV|y^5urOUacQz!OxRn@A0)|6(fcfS
zySMK3UAx<<we2Hjux{AhBgS>7+dFEix$dUZZ5%N-oOZ3*5lRQluH&uQ*Pa+^o37{D
z^{(CXYW2G9y2qQJ*uCb#9%OH&Utfd3{lXz<3EdhD=>SmzYjrOfm!k;93?39fVsa-2
zY!{736HjOcKVVHl1`9l5<R&W?H$?goiFYo;qb6cmHp!DR6tGd0>=g(hXc%WXi7C4b
z@8%DH=`dh;-b&52t+J%))F6fuYO<-pVv#~c^{I?S%t#P~Skj3f5??h!s;g$8F-bOQ
zF|9&FWy}OifJI*<KEx|D023v8Xi!rUWrAsFih&#$fh?;y#HJ=nGLtBw)Tb1ik`k6@
z3$tNwG+kH>`<$Ubs~qYgRWzNck`_vGpoxkv``9ovjgmmo4TGv!@>u}0n--O0jp;ID
z8Z{wG^))GEVyFeG6cXJhhG=TOEMplKMj(Z<51A#M5v*&bOjU_d21WT;)G>zq&|7(q
zZCV`6l$PCv8aoZUYn5|GcHfz8MXypiAIsFQVPC2BTfJf-Sml}D{+9Ja+u5tsga>z;
zRfowuMc1yidd+qLq?q1Td64I$Y<X$v-{o0WF%}QhzcQJC^C~cw<~=o5ykfOjWmS<6
mSyvqwtWiQqG)S`iP{4F8S!G!i4+YH@sZ}0941C~bW#KPuW{ao*

literal 0
HcmV?d00001

diff --git a/app/controllers/api/v2/tokens_controller.rb b/app/controllers/api/v2/tokens_controller.rb
index 1170945f..e0474e25 100644
--- a/app/controllers/api/v2/tokens_controller.rb
+++ b/app/controllers/api/v2/tokens_controller.rb
@@ -18,12 +18,6 @@ module Api
         create_action
         respond_with_resource
       end
-
-      def my_tokens
-        authorize resource_class
-        instantiate_collection
-        respond_with_collection
-      end
     end
   end
 end
diff --git a/bin/build-apidocs.sh b/bin/build-apidocs.sh
index be85012c..28931b2f 100755
--- a/bin/build-apidocs.sh
+++ b/bin/build-apidocs.sh
@@ -2,8 +2,16 @@
 
 # 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
+if [[ -x $(which open) ]]; then
+  open public/api/index.html
+fi
+
+cd $OLD_DIR
diff --git a/config/routes.rb b/config/routes.rb
index b5078d86..79db8599 100644
--- a/config/routes.rb
+++ b/config/routes.rb
@@ -70,9 +70,7 @@ Metamaps::Application.routes.draw do
         delete :stars, to: 'stars#destroy', on: :member
       end
       resources :synapses, only: [:index, :create, :show, :update, :destroy]
-      resources :tokens, only: [:create, :destroy] do
-        get :my_tokens, on: :collection
-      end
+      resources :tokens, only: [:index, :create, :destroy]
       resources :topics, only: [:index, :create, :show, :update, :destroy]
       resources :users, only: [:index, :show] do
         get :current, on: :collection
diff --git a/doc/api/api.raml b/doc/api/api.raml
index 4473a6dd..8703aae9 100644
--- a/doc/api/api.raml
+++ b/doc/api/api.raml
@@ -8,12 +8,12 @@ protocols: [ HTTPS ]
 documentation:
   - title: Getting Started
     content: !include pages/getting-started.md
-  - title: Endpoints
-    content: ""
 
 securitySchemes:
+  cookie: !include securitySchemes/cookie.raml
+  token: !include securitySchemes/token.raml
   oauth_2_0: !include securitySchemes/oauth_2_0.raml
-securedBy: [ oauth_2_0 ]
+securedBy: [ cookie, token, oauth_2_0 ]
 
 traits:
   pageable: !include traits/pageable.raml
diff --git a/doc/api/apis/metacodes.raml b/doc/api/apis/metacodes.raml
index 37cbd17a..877e1835 100644
--- a/doc/api/apis/metacodes.raml
+++ b/doc/api/apis/metacodes.raml
@@ -1,4 +1,5 @@
 #type: collection
+securedBy: [ null, cookie, token, oauth_2_0 ]
 get:
   is: [ searchable: { searchFields: "name" }, orderable, pageable ]
   responses:
@@ -7,6 +8,7 @@ get:
         application/json:
           example: !include ../examples/metacodes.json
 /{id}:
+  securedBy: [ null, cookie, token, oauth_2_0 ]
   #type: item
   get:
     responses:
diff --git a/doc/api/apis/tokens.raml b/doc/api/apis/tokens.raml
index ef7a8379..5d4eb191 100644
--- a/doc/api/apis/tokens.raml
+++ b/doc/api/apis/tokens.raml
@@ -1,4 +1,13 @@
 #type: collection
+get:
+  description: |
+    A list of the current user's tokens.
+  is: [ searchable: { searchFields: description }, pageable, orderable ]
+  responses:
+    200:
+      body:
+        application/json:
+          example: !include ../examples/tokens.json
 post:
   body:
     application/json:
@@ -11,14 +20,6 @@ post:
       body:
         application/json:
           example: !include ../examples/token.json
-/my_tokens:
-  get:
-    is: [ searchable: { searchFields: description }, pageable, orderable ]
-    responses:
-      200:
-        body:
-          application/json:
-            example: !include ../examples/tokens.json
 /{id}:
   #type: item
   delete:
diff --git a/doc/api/apis/users.raml b/doc/api/apis/users.raml
index 7f421059..1d37bc0d 100644
--- a/doc/api/apis/users.raml
+++ b/doc/api/apis/users.raml
@@ -1,4 +1,5 @@
 #type: collection
+securedBy: [ null, cookie, token, oauth_2_0 ]
 get:
   is: [ searchable: { searchFields: "name" }, orderable, pageable ]
   responses:
@@ -6,6 +7,15 @@ get:
       body:
         application/json:
           example: !include ../examples/users.json
+/{id}:
+  #type: item
+  securedBy: [ null, cookie, token, oauth_2_0 ]
+  get:
+    responses:
+      200:
+        body:
+          application/json:
+            example: !include ../examples/user.json
 /current:
   #type: item
   get:
@@ -14,11 +24,3 @@ get:
         body:
           application/json:
             example: !include ../examples/current_user.json
-/{id}:
-  #type: item
-  get:
-    responses:
-      200:
-        body:
-          application/json:
-            example: !include ../examples/user.json
diff --git a/doc/api/pages/cookie_tutorial.md b/doc/api/pages/cookie_tutorial.md
new file mode 100644
index 00000000..9481b919
--- /dev/null
+++ b/doc/api/pages/cookie_tutorial.md
@@ -0,0 +1,3 @@
+One way to access the API is through your browser. Log into metamaps.cc normally, then browse manually to https://metamaps.cc/api/v2/user/current. You should see a JSON description of your own user object in the database. You can browse any GET endpoint by simply going to that URL and appending query parameters in the URI.
+
+To run a POST or DELETE request, you can use the Fetch API. See the example in the next section.
diff --git a/doc/api/pages/getting-started.md b/doc/api/pages/getting-started.md
index c620e888..429e6971 100644
--- a/doc/api/pages/getting-started.md
+++ b/doc/api/pages/getting-started.md
@@ -1,86 +1,2 @@
-[Skip ahead to the endpoints.](#endpoints)
+There are three ways to log in: cookie-based authentication, token-based authentication, or OAuth 2. If you're testing the API or making simple scripts, cookie-based or token-based is the best. If you're developing and app and want users to be able to log into Metamaps inside your app, you'll be able to use the OAuth 2 mechanism. Check the security tab of any of the endpoints above for instructions on logging in.
 
-There are three ways to log in: cookie-based authentication, token-based authentication, or OAuth 2. If you're testing the API or making simple scripts, cookie-based or token-based is the best. If you're developing and app and want users to be able to log into Metamaps inside your app, you'll be able to use the OAuth 2 mechanism.
-
-### 1. Cookie-based authentication
-
-One way to access the API is through your browser. Log into metamaps.cc normally, then browse manually to https://metamaps.cc/api/v2/user/current. You should see a JSON description of your own user object in the database. You can browse any GET endpoint by simply going to that URL and appending query parameters in the URI.
-
-To run a POST or DELETE request, you can use the Fetch API. See the example in the next section.
-
-### 2. Token-based authentication
-
-If you are logged into the API via another means, you can create a token. Once you have this token, you can append it to a request. For example, opening a private window in your browser and browsing to `https://metamaps.cc/api/v2/user/current?token=...token here...` would show you your current user, even without logging in by another means.
-
-To get a list of your current tokens, you can log in using cookie-based authentication and run the following fetch request in your browser console (assuming the current tab is on some page within the `metamaps.cc` website.
-
-```javascript
-fetch('/api/v2/tokens', {
-  method: 'GET',
-  credentials: 'same-origin' // needed to use the cookie-based auth
-}).then(response => {
-  return response.json()
-}).then(console.log).catch(console.error)
-```
-
-If this is your first time accessing the API, this list wil be empty. You can create a token using a similar method:
-
-```javascript
-fetch('/api/v2/tokens', {
-  method: 'POST',
-  credentials: 'same-origin'
-}).then(response => {
-  return response.json()
-}).then(payload => {
-  console.log(payload)
-}).catch(console.error)
-```
-
-`payload.data.token` will contain a string which you can use to append to requests to access the API from anywhere.
-
-### 3. OAuth 2 Authentication
-
-We use a flow for Oauth 2 authentication called Authorization Code. It basically consists of an exchange of an `authorization` token for an `access token`. For more detailed info, check out the [RFC spec here](http://tools.ietf.org/html/rfc6749#section-4.1)
-
-The first step is to register your client app.
-
-#### Registering the client
-
-Set up a new client in `/oauth/applications/new`. For testing purposes, you should fill in the redirect URI field with `urn:ietf:wg:oauth:2.0:oob`. This will tell it to display the authorization code instead of redirecting to a client application (that you don't have now).
-
-#### Requesting authorization
-
-To request the authorization token, you should visit the `/oauth/authorize` endpoint. You can do that either by clicking in the link to the authorization page in the app details or by visiting manually the URL:
-
-```
-http://metamaps.cc/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=urn:ietf:wg:oauth:2.0:oob&response_type=code
-```
-
-Once you are there, you should sign in and click on `Authorize`.
-You will then see a response that contains your "authorization code", which you need to exchange for an access token.
-
-#### Requesting the access token
-
-To request the access token, you should use the returned code and exchange it for an access token. To do that you can use any HTTP client. Here's an example with `fetch`
-
-```javascript
-fetch('https://metamaps.cc/oauth/token?client_id=THE_ID&client_secret=THE_SECRET&code=RETURNED_CODE&grant_type=authorization_code&redirect_uri=urn:ietf:wg:oauth:2.0:oob', {
-  method: 'POST',
-  credentials: 'same-origin'
-}).then(response => {
-  return response.json()
-}).then(console.log).catch(console.error)
-```
-
-The response will look like
-
-```json
-{
- "access_token": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54",
- "token_type": "bearer", 
- "expires_in": 7200,
- "refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1"
-}
-```
-
-You can now make requests to the API with the access token returned.
diff --git a/doc/api/pages/oauth_2_0_tutorial.md b/doc/api/pages/oauth_2_0_tutorial.md
new file mode 100644
index 00000000..e419a621
--- /dev/null
+++ b/doc/api/pages/oauth_2_0_tutorial.md
@@ -0,0 +1,41 @@
+We use a flow for Oauth 2 authentication called Authorization Code. It basically consists of an exchange of an `authorization` token for an `access token`. For more detailed info, check out the [RFC spec here](http://tools.ietf.org/html/rfc6749#section-4.1)
+
+The first step is to register your client app.
+
+#### Registering the client
+
+Set up a new client in `/oauth/applications/new`. For testing purposes, you should fill in the redirect URI field with `urn:ietf:wg:oauth:2.0:oob`. This will tell it to display the authorization code instead of redirecting to a client application (that you don't have now).
+
+#### Requesting authorization
+
+To request the authorization token, you should visit the `/oauth/authorize` endpoint. You can do that either by clicking in the link to the authorization page in the app details or by visiting manually the URL:
+
+```
+http://metamaps.cc/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=urn:ietf:wg:oauth:2.0:oob&response_type=code
+```
+
+Once you are there, you should sign in and click on `Authorize`.
+You will then see a response that contains your "authorization code", which you need to exchange for an access token.
+
+#### Requesting the access token
+
+To request the access token, you should use the returned code and exchange it for an access token. To do that you can use any HTTP client. Here's an example with `fetch`
+
+```javascript
+fetch('https://metamaps.cc/oauth/token?client_id=THE_ID&client_secret=THE_SECRET&code=RETURNED_CODE&grant_type=authorization_code&redirect_uri=urn:ietf:wg:oauth:2.0:oob', {
+  method: 'POST',
+  credentials: 'same-origin'
+}).then(response => {
+  return response.json()
+}).then(console.log).catch(console.error)
+
+# The response will be like
+{
+ "access_token": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54",
+ "token_type": "bearer", 
+ "expires_in": 7200,
+ "refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1"
+}
+```
+
+You can now make requests to the API with the access token returned.
diff --git a/doc/api/pages/token_tutorial.md b/doc/api/pages/token_tutorial.md
new file mode 100644
index 00000000..3a46582a
--- /dev/null
+++ b/doc/api/pages/token_tutorial.md
@@ -0,0 +1,25 @@
+If you are logged into the API via another means, you can create a token. Once you have this token, you can append it to a request. For example, opening a private window in your browser and browsing to `https://metamaps.cc/api/v2/user/current?token=...token here...` would show you your current user, even without logging in by another means.
+
+To get a list of your current tokens, you can log in using cookie-based authentication and run the following fetch request in your browser console (assuming the current tab is on some page within the `metamaps.cc` website.
+
+```
+fetch('/api/v2/tokens', {
+  method: 'GET',
+  credentials: 'same-origin' // needed to use the cookie-based auth
+}).then(response => {
+  return response.json()
+}).then(console.log).catch(console.error)
+```
+
+If this is your first time accessing the API, this list wil be empty. You can create a token using a similar method:
+
+```
+fetch('/api/v2/tokens', {
+  method: 'POST',
+  credentials: 'same-origin'
+}).then(response => {
+  return response.json()
+}).then(console.log).catch(console.error)
+```
+
+`payload.data.token` will contain a string which you can use to append to requests to access the API from anywhere.
diff --git a/doc/api/securitySchemes/cookie.raml b/doc/api/securitySchemes/cookie.raml
new file mode 100644
index 00000000..fb1041b1
--- /dev/null
+++ b/doc/api/securitySchemes/cookie.raml
@@ -0,0 +1,3 @@
+description: !include ../pages/cookie_tutorial.md
+type: x-cookie
+displayName: Secured by cookie-based authentication
diff --git a/doc/api/securitySchemes/oauth_2_0.raml b/doc/api/securitySchemes/oauth_2_0.raml
index b271e03a..3a84e293 100644
--- a/doc/api/securitySchemes/oauth_2_0.raml
+++ b/doc/api/securitySchemes/oauth_2_0.raml
@@ -1,5 +1,4 @@
-description: |
-  OAuth 2.0 implementation
+description: !include ../pages/oauth_2_0_tutorial.md
 type: OAuth 2.0
 settings:
   authorizationUri: https://metamaps.cc/api/v2/oauth/authorize
diff --git a/doc/api/securitySchemes/token.raml b/doc/api/securitySchemes/token.raml
new file mode 100644
index 00000000..f83e1177
--- /dev/null
+++ b/doc/api/securitySchemes/token.raml
@@ -0,0 +1,3 @@
+description: !include ../pages/token_tutorial.md
+type: x-token
+displayName: Secured by token-based authentication
diff --git a/doc/api/templates/item.nunjucks b/doc/api/templates/item.nunjucks
new file mode 100644
index 00000000..044c24d9
--- /dev/null
+++ b/doc/api/templates/item.nunjucks
@@ -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>
diff --git a/doc/api/templates/resource.nunjucks b/doc/api/templates/resource.nunjucks
new file mode 100644
index 00000000..6bdaf2a6
--- /dev/null
+++ b/doc/api/templates/resource.nunjucks
@@ -0,0 +1,314 @@
+{% 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 %}
+                  {% if method.securedBy | first == null %}
+                    <span class="glyphicon glyphicon-transfer" title="Authentication not required"></span>
+                  {% endif %}
+                  <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 %}
+                  {% if method.securedBy | first == null %}
+                    <span class="glyphicon glyphicon-transfer" title="Authentication not required"></span>
+                  {% endif %}
+                  <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 %}
+                    {% if method.securedBy | first == null %}
+                      <span class="glyphicon glyphicon-transfer" title="Authentication not required"></span>
+                    {% endif %}
+                    <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 %}
+
+              <!-- 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 %}
+                      {% if securedBy == null %}
+                        <div class="alert alert-info">
+                          <span class="glyphicon glyphicon-transfer" title="Authentication not required"></span>
+                          This route can be accessed anonymously.</h1>
+                        </div>
+                      {% else %}
+                        {% set securityScheme = securitySchemes[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 %}
+
+                          {% 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 %}
+                        </div>
+                      {% endif %}
+                    {% endfor %}
+                  </div>
+                {% endif %}
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    {% endfor %}
+  </div>
+{% endif %}
+
+{% for resource in resource.resources %}
+  {% include "./resource.nunjucks" %}
+{% endfor %}
diff --git a/doc/api/templates/template.nunjucks b/doc/api/templates/template.nunjucks
new file mode 100644
index 00000000..6911f44e
--- /dev/null
+++ b/doc/api/templates/template.nunjucks
@@ -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>