You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@usergrid.apache.org by sn...@apache.org on 2015/08/12 19:14:47 UTC
[52/60] [abbrv] incubator-usergrid git commit: Minor refactoring in
API doc generation.
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/cbd78b6a/docs/rest-endpoints/api-docs.md
----------------------------------------------------------------------
diff --git a/docs/rest-endpoints/api-docs.md b/docs/rest-endpoints/api-docs.md
index fa39d59..51f1909 100644
--- a/docs/rest-endpoints/api-docs.md
+++ b/docs/rest-endpoints/api-docs.md
@@ -1,5 +1,28 @@
+<h1>Usergrid API Reference</h1>
+
+Methods are organized by tag. Follow the methods are the [Model Definitions](#models).
+
+<h2>Table of Contents</h2>
+
+* [Access-Tokens](#access-tokens)
+* [Activities](#activities)
+* [Admin-Users](#admin-users)
+* [App-Users](#app-users)
+* [Entities-Collections](#entities-collections)
+* [Events](#events)
+* [Groups](#groups)
+* [Organizations-Applications](#organizations-applications)
+* [Permissions-Roles](#permissions-roles)
+
+<br>
+<br>
+
+
## Methods
-### Access-Tokens Methods
+
+
+### Access-Tokens
+
<h2 class="usergrid-POST-heading">POST /management/token</h2>
@@ -44,7 +67,9 @@ __default__
* Description: Unexpected error.
* Schema: [Error](#error)
-### Activities Methods
+
+### Activities
+
<h2 class="usergrid-GET-heading">GET /{orgId}/{appId}/groups/{groupId}/feed</h2>
@@ -125,7 +150,9 @@ __default__
* Description: Unexpected error.
* Schema: [Error](#error)
-### Admin-Users Methods
+
+### Admin-Users
+
<h2 class="usergrid-GET-heading">GET /management/orgs/{orgId}/users</h2>
@@ -352,7 +379,9 @@ __default__
* Description: Unexpected error.
* Schema: [Error](#error)
-### App-Users Methods
+
+### App-Users
+
<h2 class="usergrid-GET-heading">GET /{orgId}/{appId}/users</h2>
@@ -511,7 +540,9 @@ __default__
* Description: Unexpected error.
* Schema: [Error](#error)
-### Entities-Collections Methods
+
+### Entities-Collections
+
<h2 class="usergrid-GET-heading">GET /{orgId}/{appId}/users/{userId}/{relation}</h2>
@@ -776,7 +807,9 @@ __default__
* Description: Unexpected error.
* Schema: [Error](#error)
-### Events Methods
+
+### Events
+
<h2 class="usergrid-POST-heading">POST /{orgId}/{appId}/events</h2>
@@ -803,7 +836,9 @@ __default__
* Description: Unexpected error.
* Schema: [Error](#error)
-### Groups Methods
+
+### Groups
+
<h2 class="usergrid-POST-heading">POST /{orgId}/{appId}/groups</h2>
@@ -966,7 +1001,9 @@ __default__
* Description: Unexpected error.
* Schema: [Error](#error)
-### Organizations-Applications Methods
+
+### Organizations-Applications
+
<h2 class="usergrid-POST-heading">POST /management/orgs</h2>
@@ -1217,7 +1254,9 @@ __default__
* Description: Unexpected error.
* Schema: [Error](#error)
-### Permissions-Roles Methods
+
+### Permissions-Roles
+
<h2 class="usergrid-GET-heading">GET /{orgId}/{appId}/roles</h2>
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/cbd78b6a/docs/src/main/groovy/usergrid/ApiDocGenerator.groovy
----------------------------------------------------------------------
diff --git a/docs/src/main/groovy/usergrid/ApiDocGenerator.groovy b/docs/src/main/groovy/usergrid/ApiDocGenerator.groovy
index 4952ebf..efc99e9 100644
--- a/docs/src/main/groovy/usergrid/ApiDocGenerator.groovy
+++ b/docs/src/main/groovy/usergrid/ApiDocGenerator.groovy
@@ -17,6 +17,9 @@ import com.github.mustachejava.*
import org.apache.commons.lang3.RandomStringUtils;
+/**
+ * Generates Usergrid API docs from Swagger in Markdown format.
+ */
public class ApiDocGenerator {
def parser = new SwaggerParser();
@@ -41,9 +44,11 @@ public class ApiDocGenerator {
public ApiDocGenerator() {
writer = new OutputStreamWriter(new FileOutputStream("rest-endpoints/api-docs.md"));
operationTemplate = mf.compile(
- new FileReader("${mustacheBase}/operation.mustache"), "operation");
+ new FileReader("${mustacheBase}/markdown/operation.mustache"), "operation");
modelTemplate = mf.compile(
- new FileReader("${mustacheBase}/model.mustache"), "model");
+ new FileReader("${mustacheBase}/markdown/model.mustache"), "model");
+ fileStartTemplate = mf.compile(
+ new FileReader("${mustacheBase}/markdown/file-start.mustache"), "file-start");
}
public static void main( String[] args ) {
@@ -207,15 +212,29 @@ public class ApiDocGenerator {
}
def generateFileStart() {
- // no op
+ def scope = [:];
+ def tags = [];
+ allTags.each{ tag ->
+ def atag = [:];
+ atag.name = tag;
+ atag.link = tag.toLowerCase();
+ tags.add(atag);
+ };
+ scope.tags = tags;
+ fileStartTemplate.execute(writer, scope);
+ writer.flush();
}
def generateMethodsSectionTitle() {
+ writer.println "";
writer.println "## Methods";
+ writer.println "";
}
def generateMethodsTitle(String tag) {
- writer.println "### ${tag} Methods";
+ writer.println "";
+ writer.println "### ${tag}";
+ writer.println "";
}
def generateModelsTitle() {
@@ -224,24 +243,28 @@ public class ApiDocGenerator {
}
def generateFileEnd() {
- // no op
+ writer.println "";
+ writer.println "Generated from the Usergrid Swagger definition.";
+ writer.println "";
}
}
-
+/**
+ * Generates Usergrid API docs from Swagger in HTML format.
+ */
class HtmlApiDocGenerator extends ApiDocGenerator {
public HtmlApiDocGenerator() {
writer = new OutputStreamWriter(
new FileOutputStream("rest-endpoints/api-docs.html"));
operationTemplate = mf.compile(
- new FileReader("${mustacheBase}/operation-html.mustache"), "operation");
+ new FileReader("${mustacheBase}/html/operation.mustache"), "operation");
modelTemplate = mf.compile(
- new FileReader("${mustacheBase}/model-html.mustache"), "operation");
+ new FileReader("${mustacheBase}/html/model.mustache"), "operation");
fileStartTemplate = mf.compile(
- new FileReader("${mustacheBase}/file-start-html.mustache"), "file-start");
+ new FileReader("${mustacheBase}/html/file-start.mustache"), "file-start");
fileEndTemplate = mf.compile(
- new FileReader("${mustacheBase}/file-end-html.mustache"), "file-end");
+ new FileReader("${mustacheBase}/html/file-end.mustache"), "file-end");
}
def generateFileStart() {
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/cbd78b6a/docs/src/main/resources/file-end-html.mustache
----------------------------------------------------------------------
diff --git a/docs/src/main/resources/file-end-html.mustache b/docs/src/main/resources/file-end-html.mustache
deleted file mode 100644
index 28d75b5..0000000
--- a/docs/src/main/resources/file-end-html.mustache
+++ /dev/null
@@ -1,13 +0,0 @@
-
- </div>
- <div class="col-md-1"></div>
-</div>
-
-<!-- jQuery (necessary for Bootstrap's JavaScript plugins) -->
-<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
-
-<!-- Latest compiled and minified JavaScript -->
-<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/js/bootstrap.min.js"></script>
-
-</body>
-</html>
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/cbd78b6a/docs/src/main/resources/file-start-html.mustache
----------------------------------------------------------------------
diff --git a/docs/src/main/resources/file-start-html.mustache b/docs/src/main/resources/file-start-html.mustache
deleted file mode 100644
index 642bf42..0000000
--- a/docs/src/main/resources/file-start-html.mustache
+++ /dev/null
@@ -1,21 +0,0 @@
-<html>
-<head>
- <title>{{title}}</title>
-
- <!-- Latest compiled and minified CSS -->
- <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/css/bootstrap.min.css">
-
- <!-- Optional theme -->
- <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/css/bootstrap-theme.min.css">
-
- <link rel="stylesheet" href="api-docs.css">
-
-</head>
-<body>
-
-<div class="row">
- <div class="col-md-1"></div>
- <div class="col-md-10">
-
- <h1>{{title}}</h1>
- <p>Generated from Swagger.</p>
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/cbd78b6a/docs/src/main/resources/html/file-end.mustache
----------------------------------------------------------------------
diff --git a/docs/src/main/resources/html/file-end.mustache b/docs/src/main/resources/html/file-end.mustache
new file mode 100644
index 0000000..28d75b5
--- /dev/null
+++ b/docs/src/main/resources/html/file-end.mustache
@@ -0,0 +1,13 @@
+
+ </div>
+ <div class="col-md-1"></div>
+</div>
+
+<!-- jQuery (necessary for Bootstrap's JavaScript plugins) -->
+<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
+
+<!-- Latest compiled and minified JavaScript -->
+<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/js/bootstrap.min.js"></script>
+
+</body>
+</html>
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/cbd78b6a/docs/src/main/resources/html/file-start.mustache
----------------------------------------------------------------------
diff --git a/docs/src/main/resources/html/file-start.mustache b/docs/src/main/resources/html/file-start.mustache
new file mode 100644
index 0000000..642bf42
--- /dev/null
+++ b/docs/src/main/resources/html/file-start.mustache
@@ -0,0 +1,21 @@
+<html>
+<head>
+ <title>{{title}}</title>
+
+ <!-- Latest compiled and minified CSS -->
+ <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/css/bootstrap.min.css">
+
+ <!-- Optional theme -->
+ <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/css/bootstrap-theme.min.css">
+
+ <link rel="stylesheet" href="api-docs.css">
+
+</head>
+<body>
+
+<div class="row">
+ <div class="col-md-1"></div>
+ <div class="col-md-10">
+
+ <h1>{{title}}</h1>
+ <p>Generated from Swagger.</p>
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/cbd78b6a/docs/src/main/resources/html/model.mustache
----------------------------------------------------------------------
diff --git a/docs/src/main/resources/html/model.mustache b/docs/src/main/resources/html/model.mustache
new file mode 100644
index 0000000..8672641
--- /dev/null
+++ b/docs/src/main/resources/html/model.mustache
@@ -0,0 +1,38 @@
+
+<div>
+ <a name="{{name}}"/>
+</div>
+
+<div class="panel panel-default">
+
+ <div class="panel-heading">
+ <h2 class="panel-title model-heading">{{name}}
+ <a data-toggle="collapse" data-target="#collapse-{{modelid}}"
+ href="#collapse-{{modelid}}" class="collapsed collapse-button"> </a>
+ </h2>
+ </div>
+
+ <div id="collapse-{{modelid}}" class="panel-body collapse">
+
+ <h3>Properties</h3>
+
+ <table width="80%" class="table table-striped">
+ <tr>
+ <th>Name</th>
+ <th>Type</th>
+ <th>Description</th>
+ <th>Required</th>
+ </tr>
+ {{#properties}}
+ <tr>
+ <td>{{name}}</td>
+ <td>{{type}}</td>
+ <td>{{description}}</td>
+ <td>{{required}}</td>
+ </tr>
+ {{/properties}}
+ </table>
+
+ </div>
+
+</div>
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/cbd78b6a/docs/src/main/resources/html/operation.mustache
----------------------------------------------------------------------
diff --git a/docs/src/main/resources/html/operation.mustache b/docs/src/main/resources/html/operation.mustache
new file mode 100644
index 0000000..6e15b1f
--- /dev/null
+++ b/docs/src/main/resources/html/operation.mustache
@@ -0,0 +1,43 @@
+
+<div class="panel panel-default">
+
+ <div class="panel-heading {{method}}">
+ <h2 class="panel-title {{method}}-heading">{{method}} {{url}}
+ <a data-toggle="collapse" data-target="#collapse-{{opid}}"
+ href="#collapse-{{opid}}" class="collapsed collapse-button"> </a>
+ </h2>
+ </div>
+
+ <div id="collapse-{{opid}}" class="panel-body collapse">
+
+ <p>{{description}}</p>
+
+ <h3>Parameters</h3>
+
+ <ul>
+ {{#parameters}}
+ <li>
+ <b>{{name}}</b> ({{#type}}{{type}}{{/type}}{{#schemaRef}}
+ <a href="#{{schemaAnchor}}">{{schemaRef}}</a>{{/schemaRef}}) <br>
+ {{description}} (Specified in {{in}}).
+ </li>
+ {{/parameters}}
+ </ul>
+
+ <h3>Responses</h3>
+
+ <ul>
+ {{#responses}}
+ <li>
+ <b>{{#status}}{{status}}{{/status}}{{^status}}Default{{/status}}</b>
+ <ul>
+ <li>Description: {{description}}</li>
+ <li>Schema: [<a href="#{{schemaAnchor}}">{{schema}}</a>]</li>
+ </ul>
+ </li>
+ {{/responses}}
+ </ul>
+
+ </div>
+ <!--<div class="panel-footer"></div>-->
+</div>
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/cbd78b6a/docs/src/main/resources/markdown/file-start.mustache
----------------------------------------------------------------------
diff --git a/docs/src/main/resources/markdown/file-start.mustache b/docs/src/main/resources/markdown/file-start.mustache
new file mode 100644
index 0000000..a43daa7
--- /dev/null
+++ b/docs/src/main/resources/markdown/file-start.mustache
@@ -0,0 +1,13 @@
+<h1>Usergrid API Reference</h1>
+
+Methods are organized by tag. Follow the methods are the [Model Definitions](#models).
+
+<h2>Table of Contents</h2>
+
+{{#tags}}
+* [{{name}}](#{{link}})
+{{/tags}}
+
+<br>
+<br>
+
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/cbd78b6a/docs/src/main/resources/markdown/model.mustache
----------------------------------------------------------------------
diff --git a/docs/src/main/resources/markdown/model.mustache b/docs/src/main/resources/markdown/model.mustache
new file mode 100644
index 0000000..b58788b
--- /dev/null
+++ b/docs/src/main/resources/markdown/model.mustache
@@ -0,0 +1,21 @@
+
+### {{name}}
+
+__Properties__
+
+<table width="80%" class="usergrid-table">
+ <tr>
+ <th>Name</th>
+ <th>Type</th>
+ <th>Description</th>
+ <th>Required</th>
+ </tr>
+ {{#properties}}
+ <tr>
+ <td>{{name}}</td>
+ <td>{{type}}</td>
+ <td>{{description}}</td>
+ <td>{{required}}</td>
+ </tr>
+ {{/properties}}
+</table>
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/cbd78b6a/docs/src/main/resources/markdown/operation.mustache
----------------------------------------------------------------------
diff --git a/docs/src/main/resources/markdown/operation.mustache b/docs/src/main/resources/markdown/operation.mustache
new file mode 100644
index 0000000..cce0524
--- /dev/null
+++ b/docs/src/main/resources/markdown/operation.mustache
@@ -0,0 +1,21 @@
+
+<h2 class="usergrid-{{method}}-heading">{{method}} {{url}}</h2>
+
+{{description}}
+
+<h3>Parameters</h3>
+
+{{#parameters}}
+* __{{name}}__ ({{#type}}{{type}}{{/type}}{{#schemaRef}}[{{schemaRef}}](#{{schemaAnchor}}){{/schemaRef}})
+{{description}} (Specified in {{in}}).
+{{/parameters}}
+
+<h3>Responses</h3>
+
+{{#responses}}
+__{{#status}}{{status}}{{/status}}{{^status}}Default{{/status}}__
+
+* Description: {{description}}
+* Schema: [{{schema}}](#{{schemaAnchor}})
+
+{{/responses}}
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/cbd78b6a/docs/src/main/resources/model-html.mustache
----------------------------------------------------------------------
diff --git a/docs/src/main/resources/model-html.mustache b/docs/src/main/resources/model-html.mustache
deleted file mode 100644
index 8672641..0000000
--- a/docs/src/main/resources/model-html.mustache
+++ /dev/null
@@ -1,38 +0,0 @@
-
-<div>
- <a name="{{name}}"/>
-</div>
-
-<div class="panel panel-default">
-
- <div class="panel-heading">
- <h2 class="panel-title model-heading">{{name}}
- <a data-toggle="collapse" data-target="#collapse-{{modelid}}"
- href="#collapse-{{modelid}}" class="collapsed collapse-button"> </a>
- </h2>
- </div>
-
- <div id="collapse-{{modelid}}" class="panel-body collapse">
-
- <h3>Properties</h3>
-
- <table width="80%" class="table table-striped">
- <tr>
- <th>Name</th>
- <th>Type</th>
- <th>Description</th>
- <th>Required</th>
- </tr>
- {{#properties}}
- <tr>
- <td>{{name}}</td>
- <td>{{type}}</td>
- <td>{{description}}</td>
- <td>{{required}}</td>
- </tr>
- {{/properties}}
- </table>
-
- </div>
-
-</div>
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/cbd78b6a/docs/src/main/resources/model.mustache
----------------------------------------------------------------------
diff --git a/docs/src/main/resources/model.mustache b/docs/src/main/resources/model.mustache
deleted file mode 100644
index b58788b..0000000
--- a/docs/src/main/resources/model.mustache
+++ /dev/null
@@ -1,21 +0,0 @@
-
-### {{name}}
-
-__Properties__
-
-<table width="80%" class="usergrid-table">
- <tr>
- <th>Name</th>
- <th>Type</th>
- <th>Description</th>
- <th>Required</th>
- </tr>
- {{#properties}}
- <tr>
- <td>{{name}}</td>
- <td>{{type}}</td>
- <td>{{description}}</td>
- <td>{{required}}</td>
- </tr>
- {{/properties}}
-</table>
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/cbd78b6a/docs/src/main/resources/operation-html.mustache
----------------------------------------------------------------------
diff --git a/docs/src/main/resources/operation-html.mustache b/docs/src/main/resources/operation-html.mustache
deleted file mode 100644
index 6e15b1f..0000000
--- a/docs/src/main/resources/operation-html.mustache
+++ /dev/null
@@ -1,43 +0,0 @@
-
-<div class="panel panel-default">
-
- <div class="panel-heading {{method}}">
- <h2 class="panel-title {{method}}-heading">{{method}} {{url}}
- <a data-toggle="collapse" data-target="#collapse-{{opid}}"
- href="#collapse-{{opid}}" class="collapsed collapse-button"> </a>
- </h2>
- </div>
-
- <div id="collapse-{{opid}}" class="panel-body collapse">
-
- <p>{{description}}</p>
-
- <h3>Parameters</h3>
-
- <ul>
- {{#parameters}}
- <li>
- <b>{{name}}</b> ({{#type}}{{type}}{{/type}}{{#schemaRef}}
- <a href="#{{schemaAnchor}}">{{schemaRef}}</a>{{/schemaRef}}) <br>
- {{description}} (Specified in {{in}}).
- </li>
- {{/parameters}}
- </ul>
-
- <h3>Responses</h3>
-
- <ul>
- {{#responses}}
- <li>
- <b>{{#status}}{{status}}{{/status}}{{^status}}Default{{/status}}</b>
- <ul>
- <li>Description: {{description}}</li>
- <li>Schema: [<a href="#{{schemaAnchor}}">{{schema}}</a>]</li>
- </ul>
- </li>
- {{/responses}}
- </ul>
-
- </div>
- <!--<div class="panel-footer"></div>-->
-</div>
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/cbd78b6a/docs/src/main/resources/operation.mustache
----------------------------------------------------------------------
diff --git a/docs/src/main/resources/operation.mustache b/docs/src/main/resources/operation.mustache
deleted file mode 100644
index cce0524..0000000
--- a/docs/src/main/resources/operation.mustache
+++ /dev/null
@@ -1,21 +0,0 @@
-
-<h2 class="usergrid-{{method}}-heading">{{method}} {{url}}</h2>
-
-{{description}}
-
-<h3>Parameters</h3>
-
-{{#parameters}}
-* __{{name}}__ ({{#type}}{{type}}{{/type}}{{#schemaRef}}[{{schemaRef}}](#{{schemaAnchor}}){{/schemaRef}})
-{{description}} (Specified in {{in}}).
-{{/parameters}}
-
-<h3>Responses</h3>
-
-{{#responses}}
-__{{#status}}{{status}}{{/status}}{{^status}}Default{{/status}}__
-
-* Description: {{description}}
-* Schema: [{{schema}}](#{{schemaAnchor}})
-
-{{/responses}}
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/cbd78b6a/docs/update-api-docs.sh
----------------------------------------------------------------------
diff --git a/docs/update-api-docs.sh b/docs/update-api-docs.sh
index 0885773..d11db0b 100755
--- a/docs/update-api-docs.sh
+++ b/docs/update-api-docs.sh
@@ -1,4 +1,4 @@
#!/usr/bin/env bash
# Updating API Docs requires Mustache.java
-groovy src/main/groovy/ApiDocGenerator.groovy
+groovy src/main/groovy/usergrid/ApiDocGenerator.groovy