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/03 23:19:00 UTC
[4/9] incubator-usergrid git commit: Switch over to generating
api-docs via Groovy, Swagger and Mustache.java.
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/445ac3ec/docs/rest-endpoints/sources/collections.txt
----------------------------------------------------------------------
diff --git a/docs/rest-endpoints/sources/collections.txt b/docs/rest-endpoints/sources/collections.txt
deleted file mode 100644
index cb0370b..0000000
--- a/docs/rest-endpoints/sources/collections.txt
+++ /dev/null
@@ -1 +0,0 @@
-End-Point Method Content-type Description Detail
/{org_id}/{app_id}/ GET application/json Retrieve all collections Detail
/{org_id}/{app_id}/{collection} POST application/json Create a new entity or collection Detail
/{org_id}/{app_id}/{collection}/{identifier} GET application/json Retrieve an entity Detail
/{org_id}/{app_id}/{collection}/{identifier} PUT application/json Update an entity Detail
/{org_id}/{app_id}/{collection}/{identifier} DELETE application/json Delete an entity Detail
/{org_id}/{app_id}/{collection}?{query} GET application/json Query a collection Detail
/{org_id}/{app_id}/{collection}?{query} PUT application/json Update a collection by query Detail
/{org_id}/{app_id}/{collection}/{entity_id}/{relationship}?{query} GET application/json Query an entity's collections or connections Detail
/{org_id}/{app_id}/{collection}/{first_entity_id}/{relationship}/{second_entity_id} POST application/json Add an entity to a collection or create a connection Detail
/{org_id}/{app_
id}/{collection}/{first_entity_id}/{relationship}/{second_entity_type}/{second_entity_id} POST application/json Add an entity to a collection or create a connection Detail
/{org_id}/{app_id}/{collection}/{first_entity_id}/{relationship}/{second_entity_id}/{second_entity_type}/{second_entity_id} DELETE application/json Remove an entity from a collection or delete a connection Detail
/{org_id}/{app_id}/{collection}/{first_entity_id}/{relationship}/{second_entity_type}/{second_entity_id} DELETE application/json Remove an entity from a collection or delete a connection Detail
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/445ac3ec/docs/rest-endpoints/sources/csv2md.groovy
----------------------------------------------------------------------
diff --git a/docs/rest-endpoints/sources/csv2md.groovy b/docs/rest-endpoints/sources/csv2md.groovy
deleted file mode 100644
index 25815d0..0000000
--- a/docs/rest-endpoints/sources/csv2md.groovy
+++ /dev/null
@@ -1,43 +0,0 @@
-def dir = new File(".");
-def files = dir.list();
-files.each() { fileName ->
- if ( fileName.endsWith(".txt") ) {
-
- def baseName = fileName.substring(0, fileName.length() - 4);
-
- def outputFile = new File("../" + baseName + ".md");
- outputFile.withWriter('utf-8') { writer ->
-
- def inputFile = new File(fileName);
- def count = 0;
- writer.writeLine "# ${baseName.capitalize()}"
- writer.writeLine ""
- writer.writeLine ""
- writer.writeLine "<!-- DO NOT EDIT THIS GENERATED FILE -->";
- writer.writeLine ""
- writer.writeLine "<table class='usergrid-table rest-endpoints-table'>";
-
- inputFile.eachLine { line ->
- def parts = line.split("\\t");
- def evenodd = count % 2 ? "even" : "odd";
- if ( count == 0 ) {
- writer.writeLine " <tr>";
- parts.each() { part ->
- writer.writeLine " <th>" + part + "</th>";
- }
- writer.writeLine " </tr>";
- } else {
- writer.writeLine " <tr class='ug-${evenodd} usergrid-table'>";
- parts.each() { part ->
- writer.writeLine " <td>" + part + "</td>";
- }
- writer.writeLine " </tr>";
- }
- count++;
- }
- writer.writeLine "</table>";
-
- }
- }
-}
-
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/445ac3ec/docs/rest-endpoints/sources/events.txt
----------------------------------------------------------------------
diff --git a/docs/rest-endpoints/sources/events.txt b/docs/rest-endpoints/sources/events.txt
deleted file mode 100644
index 20a4178..0000000
--- a/docs/rest-endpoints/sources/events.txt
+++ /dev/null
@@ -1 +0,0 @@
-End-Point Method Content-type Description Detail
/{org_id}/{app_id}/events POST application/json Create an event Detail
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/445ac3ec/docs/rest-endpoints/sources/groups.txt
----------------------------------------------------------------------
diff --git a/docs/rest-endpoints/sources/groups.txt b/docs/rest-endpoints/sources/groups.txt
deleted file mode 100644
index e94dcf9..0000000
--- a/docs/rest-endpoints/sources/groups.txt
+++ /dev/null
@@ -1 +0,0 @@
-End-Point Method Content-type Description Detail
/{org_id}/{app_id}/groups POST application/json Create a new group Detail
/{org_id}/{app_id}/groups/{identifier}/users/{uuid|username} POST application/json Add a user to a group Detail
/{org_id}/{app_id}/groups/{identifier} GET application/json Get a group Detail
/{org_id}/{app_id}/groups/{identifier} PUT application/json Update a group Detail
/{org_id}/{app_id}/groups/{identifier}/users/{uuid|username} DELETE application/json Delete user from a group Detail
/{org_id}/{app_id}/groups/{identifier}/feed GET application/json Get a group's feed Detail
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/445ac3ec/docs/rest-endpoints/sources/organizations.txt
----------------------------------------------------------------------
diff --git a/docs/rest-endpoints/sources/organizations.txt b/docs/rest-endpoints/sources/organizations.txt
deleted file mode 100644
index d3cd079..0000000
--- a/docs/rest-endpoints/sources/organizations.txt
+++ /dev/null
@@ -1 +0,0 @@
-End-Point Method Description Detail
/management/organizations POST application/json Create an organization Detail
/management/organizations/{identifier} GET application/json Retrieve an organization Detail
/management/organizations/{identifier}/activate?token={token}&confirm={confirm_email} GET application/json Activate an organization Detail
/management/organizations/{identifier}/reactivate GET application/json Reactivate an organization Detail
/management/organizations/{identifier}/credentials POST application/json Generate organization client credentials Detail
/management/organizations/{identifier}/credentials GET application/json Retrieve organization client credentials Detail
/management/organizations/{identifier}/feed GET application/json Retrieve an organization's activity feed Detail
/management/organizations/{identifier}/apps POST application/json Create an organization application Detail
/management/organizations/{identifier}/applications|apps/{app_name}|{uuid}/ credenti
als POST application/json Generate credentials for an organization application Detail
/management/organizations/{identifier}/applications|apps/ {app_name}|{uuid}/credentials GET application/json Get credentials for an organization application Detail
/management/organizations/{identifier}/applications|apps GET application/json Get the applications in an organization Detail
/management/organizations/{identifier}/users/{username|email|uuid} PUT application/json Adding an admin user to an organization Detail
/management/organizations/{identifier}/users GET application/json Getting the admin users in an organization Detail
/management/organizations/{org-identifier}/users/{user-identifier} DELETE application/json Removing an admin user from an organization Detail
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/445ac3ec/docs/rest-endpoints/sources/roles.txt
----------------------------------------------------------------------
diff --git a/docs/rest-endpoints/sources/roles.txt b/docs/rest-endpoints/sources/roles.txt
deleted file mode 100644
index bfd2d33..0000000
--- a/docs/rest-endpoints/sources/roles.txt
+++ /dev/null
@@ -1 +0,0 @@
-End-Point Method Description Detail
/{org_id}/{app_id}/roles POST application/json Create a new role Detail
/{org_id}/{app_id}/roles GET application/json Get the roles in an application Detail
/{org_id}/{app_id}/roles/{rolename} DELETE application/json Delete a role Detail
/{org_id}/{app_id}/roles/{rolename|role_id}/permissions GET application/json Get permissions for a role Detail
/{org_id}/{app_id}/roles/{rolename|role_id}/permissions POST application/json Add permissions to a role Detail
/{org_id}/{app_id}/roles/{rolename|role_id}/permissions?permission={grant_url_pattern} DELETE application/json Delete permissions from a role Detail
/{org_id}/{app_id}/roles/{role_id}/users/{uuid|username}/roles/{role_id} POST application/json Add a user to a role Detail
/{org_id}/{app_id}/users/{identifier}/roles/{role_id} POST application/json Add a user to a role Detail
/{org_id}/{app_id}/roles/{role_id}/users GET application/json Get the users in a role Detail
/{org_id}/{app_id}/roles/{role_
id}/users/{uuid|username} DELETE application/json Delete a user from a role Detail
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/445ac3ec/docs/rest-endpoints/sources/users.txt
----------------------------------------------------------------------
diff --git a/docs/rest-endpoints/sources/users.txt b/docs/rest-endpoints/sources/users.txt
deleted file mode 100644
index f0f91c5..0000000
--- a/docs/rest-endpoints/sources/users.txt
+++ /dev/null
@@ -1 +0,0 @@
-End-Point Method Description Detail
/{org_id}/{app_id}/users POST application/json Create a user in the users collection Detail
/{org_id}/{app_id}/users/{user}/ password POST application/json Set a user's password or reset the user's existing password Detail
/{org_id}/{app_id}/users/{identifier} GET application/json Retrieve a user Detail
/{org_id}/{app_id}/users/{identifier} PUT application/json Update a user Detail
/{org_id}/{app_id}/users/{identifier} DELETE application/json Delete a user Detail
/{org_id}/{app_id}/users?{query} GET application/json Query to get users Detail
/{org_id}/{app_id}/groups/{group-identifier}/users/{user-identifier} POST application/json Add a user to a group Detail
/{org_id}/{app_id}/{collection}/{first_entity_id}/{relationship}/{second_entity_id} POST application/json Add a user to a collection or create a connection Detail
/{org_id}/{app_id}/{collection}/{first_entity_id}/{relationship}/{second_entity_type}/{second_entity_id} POST application/json Ad
d a user to a collection or create a connection Detail
/{org_id}/{app_id}/{collection}/{first_entity_id}/{relationship}/{second_entity_id} DELETE application/json Remove a user from a collection or delete a connection Detail
/{org_id}/{app_id}/{collection}/{first_entity_id}/{relationship}/second_entity_type}/{second_entity_id} DELETE application/json Remove a user from a collection or delete a connection Detail
/{org_id}/{app_id}/users/{identifier}/{relationship}?{query} GET application/json Query a user's collections or connections Detail
/{org_id}/{app_id}/users/{identifier}/feed GET application/json Get a user's feed Detail
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/445ac3ec/docs/rest-endpoints/users.md
----------------------------------------------------------------------
diff --git a/docs/rest-endpoints/users.md b/docs/rest-endpoints/users.md
deleted file mode 100644
index 48305f8..0000000
--- a/docs/rest-endpoints/users.md
+++ /dev/null
@@ -1,90 +0,0 @@
-# Users
-
-
-<!-- DO NOT EDIT THIS GENERATED FILE -->
-
-<table class='usergrid-table rest-endpoints-table'>
- <tr>
- <th>End-Point</th>
- <th>Method</th>
- <th>Description</th>
- <th>Detail</th>
- </tr>
- <tr class='ug-even usergrid-table'>
- <td>/{org_id}/{app_id}/users</td>
- <td>POST</td>
- <td>application/json</td>
- <td>Create a user in the users collection</td>
- <td>Detail</td>
- </tr>
- <tr class='ug-odd usergrid-table'>
- <td>/{org_id}/{app_id}/users/{user}/ password</td>
- <td>POST</td>
- <td>application/json</td>
- <td>Set a user's password or reset the user's existing password</td>
- <td>Detail</td>
- </tr>
- <tr class='ug-even usergrid-table'>
- <td>/{org_id}/{app_id}/users/ {uuid|username|email_address}</td>
- <td>GET</td>
- <td>application/json</td>
- <td>Retrieve a user</td>
- <td>Detail</td>
- </tr>
- <tr class='ug-odd usergrid-table'>
- <td>/{org_id}/{app_id}/users/ {uuid|username}</td>
- <td>PUT</td>
- <td>application/json</td>
- <td>Update a user</td>
- <td>Detail</td>
- </tr>
- <tr class='ug-even usergrid-table'>
- <td>/{org_id}/{app_id}/users/{uuid|username}</td>
- <td>DELETE</td>
- <td>application/json</td>
- <td>Delete a user</td>
- <td>Detail</td>
- </tr>
- <tr class='ug-odd usergrid-table'>
- <td>/{org_id}/{app_id}/users?{query}</td>
- <td>GET</td>
- <td>application/json</td>
- <td>Query to get users</td>
- <td>Detail</td>
- </tr>
- <tr class='ug-even usergrid-table'>
- <td>/{org_id}/{app_id}/groups/ {uuid|groupname}/users/{uuid|username}</td>
- <td>POST</td>
- <td>application/json</td>
- <td>Add a user to a group</td>
- <td>Detail</td>
- </tr>
- <tr class='ug-odd usergrid-table'>
- <td>/{org_id}/{app_id}/{collection}/ {first_entity_id}/{relationship}/ {second_entity_id} or /{org_id}/{app_id}/{collection}/ {first_entity_id}/{relationship}/ {second_entity_type}/{second_entity_id}</td>
- <td>POST</td>
- <td>application/json</td>
- <td>Add a user to a collection or create a connection</td>
- <td>Detail</td>
- </tr>
- <tr class='ug-even usergrid-table'>
- <td>/{org_id}/{app_id}/{collection}/ {first_entity_id}/{relationship}/ {second_entity_id} or /{org_id}/{app_id}/{collection}/ {first_entity_id}/{relationship}/ {second_entity_type}/{second_entity_id}</td>
- <td>DELETE</td>
- <td>application/json</td>
- <td>Remove a user from a collection or delete a connection</td>
- <td>Detail</td>
- </tr>
- <tr class='ug-odd usergrid-table'>
- <td>/{org_id}/{app_id}/users/{uuid|username}/ {relationship}?{query}</td>
- <td>GET</td>
- <td>application/json</td>
- <td>Query a user's collections or connections</td>
- <td>Detail</td>
- </tr>
- <tr class='ug-even usergrid-table'>
- <td>/{org_id}/{app_id}/users/ {uuid|username}/feed</td>
- <td>GET</td>
- <td>application/json</td>
- <td>Get a user's feed</td>
- <td>Detail</td>
- </tr>
-</table>
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/445ac3ec/docs/src/main/groovy/ApiDocGenerator.groovy
----------------------------------------------------------------------
diff --git a/docs/src/main/groovy/ApiDocGenerator.groovy b/docs/src/main/groovy/ApiDocGenerator.groovy
new file mode 100644
index 0000000..810ca53
--- /dev/null
+++ b/docs/src/main/groovy/ApiDocGenerator.groovy
@@ -0,0 +1,176 @@
+/*
+ * Generates API docs from Swagger.
+ */
+
+// Depdency management with Grape:
+// http://docs.groovy-lang.org/latest/html/documentation/grape.html
+
+import io.swagger.models.parameters.RefParameter
+@Grab(group = 'io.swagger', module = 'swagger-parser', version = '1.0.8')
+@Grab(group = 'io.swagger', module = 'swagger-compat-spec-parser', version = '1.0.8')
+@Grab(group = 'com.github.spullara.mustache.java', module = 'compiler', version = '0.8.18-SNAPSHOT')
+
+import io.swagger.parser.*;
+import io.swagger.models.*;
+import com.github.mustachejava.*;
+
+
+public class ApiDocGenerator {
+
+ def parser = new SwaggerParser();
+ def swagger = parser.read("src/main/resources/usergrid-swagger.yaml");
+
+ // Mustache reference: http://mustache.github.io/mustache.5.html
+ // mustache.java info: https://github.com/spullara/mustache.java
+ def writer = new OutputStreamWriter(new FileOutputStream("rest-endpoints/api-docs.md"));
+ def mf = new DefaultMustacheFactory();
+
+ def mustacheBase = "src/main/resources";
+ def operationTemplate = mf.compile(new FileReader("${mustacheBase}/operation.mustache"), "operation");
+ def modelTemplate = mf.compile(new FileReader("${mustacheBase}/model.mustache"), "operation");
+
+
+ public static void main( String[] args ) {
+ def adg = new ApiDocGenerator();
+ adg.generate();
+ }
+
+ def generate() {
+
+ // organize methods by tag
+ def tagsToUrlOps = [:]
+
+ swagger.getPaths().each { pathEntry ->
+ def url = pathEntry.key;
+ def path = pathEntry.value;
+
+ def tag; // assume each opeation has only one tag
+ def method;
+ def operation;
+
+ if (path.get != null) {
+ tag = path.get.tags[0];
+ method = "GET";
+ operation = path.get;
+ }
+ if (path.post != null) {
+ tag = path.post.tags[0];
+ method = "POST";
+ operation = path.post;
+ }
+ if (path.delete != null) {
+ tag = path.delete.tags[0];
+ method = "DELETE";
+ operation = path.delete;
+ }
+ if (path.put != null) {
+ tag = path.put.tags[0];
+ method = "PUT";
+ operation = path.put;
+ }
+
+ def urlOps = tagsToUrlOps[tag];
+ if ( urlOps == null ) {
+ urlOps = [];
+ tagsToUrlOps[tag] = urlOps;
+ }
+ def urlOp = [:];
+ urlOp.url = url;
+ urlOp.method = method;
+ urlOp.operation = operation;
+ urlOps.add(urlOp);
+ }
+
+ writer.println "\n# Methods";
+
+ tagsToUrlOps.each { entry ->
+ def tag = entry.key;
+ def urlOps = entry.value;
+// writer.println "\n<div class='hr'/>";
+ writer.println "\n## ${tag} Methods";
+ urlOps.each { urlOp ->
+ formatOperation( urlOp );
+ };
+ };
+
+ writer.println "\n# Models";
+
+ swagger.getDefinitions().each { definitionEntry ->
+ def name = definitionEntry.key;
+ def model = definitionEntry.value;
+ formatModel( name, model );
+ };
+ }
+
+ def formatOperation( urlOp ) {
+
+ def url = urlOp.url;
+ def method = urlOp.method;
+ def op = urlOp.operation;
+
+ // put responses in array form, mustache doesn't play nice with associative arrays
+ def responses = [];
+ op.getResponses().each { responseEntry ->
+ def response = [:];
+ response.status = responseEntry.key;
+ response.description = responseEntry.value.description;
+ if ( responseEntry.value.schema != null) {
+ response.schema = responseEntry.value.schema.ref;
+ response.schemaAnchor = responseEntry.value.schema.ref.toLowerCase();
+ }
+ responses.add(response);
+ }
+
+ def params = [];
+ op.getParameters().each { parameter ->
+ def param = [:];
+ param.name = parameter.name;
+ param.required = parameter.required;
+ param.description = parameter.description;
+ param.in = parameter.in;
+ if (parameter.in == "body" && parameter.schema != null) {
+ param.schemaRef = parameter.schema.ref;
+ param.schemaAnchor = parameter.schema.ref.toLowerCase();
+ } else if (parameter.in == "path") {
+ param.type = parameter.type;
+ }
+ params.add(param);
+ }
+
+ def scope = [:];
+ scope.url = url;
+ scope.method = method;
+ scope.description = op.getDescription();
+ scope.summary = op.getSummary();
+ scope.tags = op.getTags();
+ scope.responses = responses;
+ scope.parameters = params;
+
+ operationTemplate.execute(writer, scope);
+ writer.flush();
+ }
+
+ def formatModel(String name, Model model) {
+
+ // put properties in array form, mustache doesn't play nice with associative arrays
+ def props = [];
+ model.getProperties().each { property ->
+ def prop = [:];
+ prop.name = property.key;
+ prop.type = property.value.type;
+ prop.title = property.value.title;
+ prop.description = property.value.description;
+ prop.access = property.value.access;
+ prop.readOnly = property.value.readOnly;
+ prop.required = property.value.required;
+ prop.position = property.value.position;
+ props.add(prop);
+ };
+ def scope = [:];
+ scope.name = name;
+ scope.properties = props;
+ modelTemplate.execute(writer, scope);
+ writer.flush();
+ }
+}
+
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/445ac3ec/docs/src/main/resources/model.mustache
----------------------------------------------------------------------
diff --git a/docs/src/main/resources/model.mustache b/docs/src/main/resources/model.mustache
new file mode 100644
index 0000000..4e6e8b5
--- /dev/null
+++ b/docs/src/main/resources/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/445ac3ec/docs/src/main/resources/operation.mustache
----------------------------------------------------------------------
diff --git a/docs/src/main/resources/operation.mustache b/docs/src/main/resources/operation.mustache
new file mode 100644
index 0000000..d19ec70
--- /dev/null
+++ b/docs/src/main/resources/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}}