praxis-docs-code-examples 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 78b2b5d8cbc88958c1bd5c2696235df1bc5b1b5e
+  data.tar.gz: 6fcb0852e63038db72e9508a8e68ab1a7670d2a2
+SHA512:
+  metadata.gz: bfebbb6a3f42111d8b75cc81f0043293c6f3af9aa8cd7715d973135e07b5c08e3f4a2315e60e1bf32a99f07f6d1a55239e6ece701f7de863e10047f460646150
+  data.tar.gz: f81c7ad2152eb37b43714c46adee8f022048ff122993eff77b048a3679119df7140091764ba324f771e95fb14af76b50874caf44c173b9bf75dbb064a0f82fe4

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in praxis-docs-code-examples.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Jakub Hampl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,50 @@
+# Praxis Docs Code Examples
+
+This is a Praxis Plugin that adds code examples to the Praxis Docs Browser. Why
+should you use it? Let's talk about a few reasons you probably shouldn't use it:
+
+- Praxis currently doesn't have a way to describe an authentication mechanism for
+  the supported APIs. So if your API is authenticated, the examples won't actually work.
+- The code generators don't necessarily (yet!) take into consideration everything
+  that can be expressed with the the Praxis design language and may fall
+  over. I recommend reviewing each example before publishing the generated code
+  examples to clients.
+- The examples are fairly uninteresting uses of the API. A handwritten example of
+  doing something actually interesting with your API might be more interesting for
+  the reader.
+
+That being said, this repo can serve as a good starting point for writing your own
+code generators for the Praxis doc browser.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'praxis-docs-code-examples'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install praxis-docs-code-examples
+
+## Usage
+
+Add `application.bootloader.use Praxis::DocsCodeExamples` to your Praxis bootloader.
+
+## Development
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/rightsale/praxis-docs-code-examples.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/api_browser/generators/javascript.js

@@ -0,0 +1,121 @@
+angular.module('PraxisDocBrowser').config(function(ExamplesProvider) {
+
+  function basicCode(action, info) {
+    var code = 'var request = new XMLHttpRequest();\n\n';
+    if (!info.endpoint) {
+      //throw 'Endpoint not defined in schema';
+    }
+    code += 'request.open(\'' + action.urls[0].verb +'\', \'' + info.endpoint + action.urls[0].example + '\');\n\n';
+
+    code += _.map(action.headers.type.attributes, function(value, key) {
+      return 'request.setRequestHeader(\''+ key + '\', \''+ value.example + '\');'
+    }).join('\n')
+
+    code += '\nrequest.setRequestHeader(\'Content-Type\', \'' + _.get(action, 'payload.examples.json.content_type', 'text/json') + '\');\n\n';
+
+    code += '\nrequest.onreadystatechange = function () {\n' +
+            '  if (this.readyState === 4) {\n' +
+            '    console.log(\'Status:\', this.status);\n' +
+            '    console.log(\'Headers:\', this.getAllResponseHeaders());\n' +
+            '    console.log(\'Body:\', this.responseText);\n' +
+            '  }\n' +
+            '};\n\n';
+
+    if (action.payload) {
+      code += 'var body = ' + action.payload.examples.json.body + ';\n\n';
+      code += 'request.send(JSON.stringify(body));';
+    } else {
+      code += 'request.send();';
+    }
+    return code;
+  }
+
+  function angularCode(resource, action, info) {
+    if (!info.endpoint) {
+      //throw 'Endpoint not defined in schema';
+    }
+    var code = '// Define Client:\n';
+    code += 'angular.module(\'Models\').service(\'' + resource.display_name + '\', [\'$http\', function($http) {\n';
+    code += '  this.' + _.camelCase(action.name) + ' = function(data) {\n';
+    // _.each(_.get(action, 'params.type.attributes'), function(opts, val) {
+    //   if (opts.source === 'url') {
+    //     code += '    var ' + _.camelCase(val) + ' = data.' + _.camelCase(val) + ';\n';
+    //   }
+    // });
+    code += '    return $http({\n';
+    code += '      method: \'' + action.urls[0].verb + '\',\n';
+    code += '      url: \'' + info.endpoint + (action.urls[0].path.replace(/:([\w_]+)/g, function(m, variable) {
+      return '\' + data.' + _.camelCase(variable) + ' + \'';
+    }) + '\'').replace(/ \+ ''$/, '') + ',\n';
+    var params = _.get(action, 'params.type.attributes', {});
+    if (_.some(params, {source: 'query'})) {
+      code += '      params: {\n';
+      _.each(params, function(opts, name) {
+        if (opts.source === 'query') {
+          code += '        ' + name + ': data.' + _.camelCase(name) + ',\n';
+        }
+      });
+      code += '      },\n'
+    }
+    var headers = _.get(action, 'headers.type.attributes', {});
+    if (_.keys(headers).length > 0) {
+      code += '      headers: {\n';
+      _.each(headers, function(opts, name) {
+        if (opts.values && opts.values.length === 1) {
+          code += '        ' + _.snakeCase(name) + ': \'' + opts.values[0] + '\',\n';
+        } else {
+          code += '        ' + _.snakeCase(name) + ': data.' + _.camelCase(name) + ',\n';
+        }
+      });
+      code += '      },\n';
+    }
+    var payload = _.get(action, 'payload.type.attributes', {});
+    if (_.keys(payload).length > 0) {
+      code += '      data: {\n';
+      _.each(payload, function(opts, name) {
+        if (opts.values && opts.values.length === 1) {
+          code += '        ' + name + ': \'' + opts.values[0] + '\',\n';
+        } else {
+          code += '        ' + name + ': data.' + _.camelCase(name) + ',\n';
+        }
+      });
+      code += '      },\n'
+    }
+    code += '    });\n';
+    code += '  };\n'
+    code += '}]);\n\n';
+    code += '// Example Usage:\n';
+    code += 'angular.module(\'Controllers\').controller(\'' + resource.display_name + 'Controller\', [\'' + resource.display_name + '\', \'$scope\', function(' + resource.display_name + ', $scope) {\n';
+    code += '  ' + resource.display_name + '.' + _.camelCase(action.name) + '({\n';
+    _.each(params, function(opts, name) {
+      code += '    ' + name + ': ' + JSON.stringify(opts.example, null, 2) +',\n';
+    });
+    _.each(headers, function(opts, name) {
+      if (opts.example && (!opts.values || opts.values.length != 1)) {
+        code += '    ' + _.snakeCase(name) + ': ' + JSON.stringify(opts.example, null, 2) +',\n';
+      }
+    });
+    _.each(payload, function(opts, name) {
+      if (opts.example && (!opts.values || opts.values.length != 1)) {
+        code += '    ' + name + ': ' + JSON.stringify(opts.example, null, 2) +',\n';
+      }
+    });
+    code += '  }).then(function(result) {\n';
+    code += '    $scope.result = result.data;\n'
+    code += '  });\n';
+    code += '}]);\n';
+    return code;
+  }
+
+  ExamplesProvider.register('browser-javascript', 'JavaScript', function($compile, $context, Documentation) {
+    "ngInject";
+    return Documentation.info($context.version).then(function(info) {
+      var template = '<h3>Plain JavaScript</h3>\n<pre highlight="javascript">' + basicCode($context.action, info) + '</pre>\n\n';
+
+      template += '<h3>Angular</h3>\n<pre highlight="javascript">' + angularCode($context.resource, $context.action, info) + '</pre>\n\n';
+
+
+      return $compile(template);
+    });
+  });
+});

data/lib/api_browser/generators/ruby.js

@@ -0,0 +1,64 @@
+angular.module('PraxisDocBrowser').config(function(ExamplesProvider) {
+
+  function basicCode(action, info) {
+    var code = 'require \'restclient\'\n\n';
+    if (!info.endpoint) {
+      //throw 'Endpoint not defined in schema';
+    }
+    if (action.headers) {
+      code += 'headers = {\n';
+      _.each(_.get(action, 'headers.type.attributes'), function(value, key) {
+        code +=  '  ' + JSON.stringify(key) + ' => '+ JSON.stringify(value.example) + ',\n'
+      });
+      code += '}\n'
+    }
+
+    if (action.payload) {
+      code += 'payload = {\n'
+      _.each(_.get(action, 'payload.type.attributes'), function(value, key) {
+        if (value.example) {
+          code +=  '  :' + key + ' => '+ JSON.stringify(value.example) + ',\n';
+        }
+      })
+      code += '}\n'
+    }
+
+    var params = '';
+    _.each(_.get(action, 'params.type.attributes'), function(opts, name) {
+      if (opts.source === 'query') {
+        params += '  :' + name + ' => ' + JSON.stringify(opts.example) + ',\n';
+      }
+    });
+
+    var signature = 'response = RestClient.' + action.urls[0].verb.toLowerCase() + ' \'' + info.endpoint + action.urls[0].example + '\'';
+
+    if (action.payload) {
+      signature += ', payload';
+    }
+
+    if (action.headers && params.length > 0) {
+      code += 'headers[:params] = {\n' + params + '}\n';
+      signature += ', headers'
+    } else if (params.length > 0) {
+      'params = {\n' + params + '}\n'
+      signature += ', :params => params'
+    } else {
+      signature += ', headers'
+    }
+
+    code += signature;
+
+    code += '\n\nputs response.inspect'
+
+    return code;
+  }
+
+  ExamplesProvider.register('ruby', 'Ruby', function($compile, $context, Documentation) {
+    "ngInject";
+    return Documentation.info($context.version).then(function(info) {
+      var template = '<pre highlight="ruby">' + basicCode($context.action, info) + '</pre>\n\n';
+
+      return $compile(template);
+    });
+  });
+});

data/lib/praxis-docs-code-examples.rb

@@ -0,0 +1,15 @@
+require "praxis-docs-code-examples/version"
+
+module Praxis
+  class DocsCodeExamples < ::Praxis::Plugin
+    include Singleton
+    def setup!
+      puts "Registering"
+      register_doc_browser_plugin File.join(File.dirname(__FILE__), 'api_browser')
+    end
+
+    def config_key
+      :docs_code_examples
+    end
+  end
+end

data/lib/praxis-docs-code-examples/version.rb

@@ -0,0 +1,3 @@
+module PraxisDocsCodeExamples
+  VERSION = "0.1.0"
+end

data/praxis-docs-code-examples.gemspec

@@ -0,0 +1,21 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'praxis-docs-code-examples/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "praxis-docs-code-examples"
+  spec.version       = PraxisDocsCodeExamples::VERSION
+  spec.authors       = ["Jakub Hampl"]
+  spec.email         = ["honitom@seznam.cz"]
+
+  spec.summary       = %q{Code examples for the Praxis Docs Browser }
+  spec.homepage      = "https://github.com/rightscale/praxis-docs-code-examples"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "rake", "~> 10.0"
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: praxis-docs-code-examples
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jakub Hampl
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-01-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+description: 
+email:
+- honitom@seznam.cz
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/api_browser/generators/curl.js
+- lib/api_browser/generators/javascript.js
+- lib/api_browser/generators/ruby.js
+- lib/praxis-docs-code-examples.rb
+- lib/praxis-docs-code-examples/version.rb
+- praxis-docs-code-examples.gemspec
+homepage: https://github.com/rightscale/praxis-docs-code-examples
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Code examples for the Praxis Docs Browser
+test_files: []