http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/fc52c0e0/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/fc52c0e0/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/fc52c0e0/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/fc52c0e0/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/fc52c0e0/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/fc52c0e0/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/fc52c0e0/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/fc52c0e0/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/fc52c0e0/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/fc52c0e0/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/fc52c0e0/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/fc52c0e0/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/fc52c0e0/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/fc52c0e0/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/fc52c0e0/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/fc52c0e0/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
