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}}