textualize 0.1.0

data/lib/textualize/templates/new/apis/documentation/authentication.yaml

@@ -0,0 +1,21 @@
+description: |
+  OAuth2 is a protocol that lets external apps request authorization to private
+  details in a user's account without getting their password. This is preferred
+  over Basic Authentication because tokens can be limited to specific types of
+  data, and can be revoked by users at any time.
+type: OAuth 2.0
+describedBy:
+  headers:
+    Authorization:
+      description: Used to send a valid OAuth 2 access token.
+      type: string
+  responses:
+    404:
+      description: Unauthorized
+settings:
+  authorizationUri: https://app.my-awesome-restaurant.com/login/oauth/authorize
+  accessTokenUri: https://app.my-awesome-restaurant.com/login/oauth/access_token
+  authorizationGrants: [ code ]
+  scopes:
+    - "customer"
+    - "staff"

data/lib/textualize/templates/new/apis/documentation/http_statuses.md

@@ -0,0 +1,26 @@
+# HTTP Status Code Summary
+
+We use conventional HTTP response codes to indicate success or failure of an
+API request. In general, codes in the 2xx range indicate success, codes in the
+4xx range indicate an error that resulted from the provided information (e.g. a
+required parameter was missing, a charge failed, etc.), and codes in the 5xx
+range indicate an error with our servers.
+
+
+    | Code                               | Description                               |
+    |------------------------------------|-------------------------------------------|
+    | 200 - OK                           | Everything worked as expected.            |
+    | 201 - Created                      | New resource being created                |
+    | 400 - Bad Request                  | Often missing a required parameter.       |
+    | 401 - Unauthorized                 | No valid API key provided.                |
+    | 402 - Request Failed               | Parameters were valid but request failed. |
+    | 404 - Not Found                    | The requested item doesn't exist.         |
+    | 500, 502, 503, 504 - Server Errors | Something went wrong on our end.  |
+
+# Errors
+
+    | ATTRIBUTES         | Description                                                                 |
+    |--------------------|-----------------------------------------------------------------------------|
+    | code               | The same as HTTP status code. This can help other clients are easy to read. |
+    | details (optional) | List of validation errors. ex: {name: [{error: :blank}]}                    |
+    | message (optional) | A human-readable message giving more details about the error.               |

data/lib/textualize/templates/new/apis/errors.yaml

@@ -0,0 +1,6 @@
+400: !include ./responses/400.yaml
+401: !include ./responses/401.yaml
+403: !include ./responses/403.yaml
+404: !include ./responses/404.yaml
+422: !include ./responses/422.yaml
+500: !include ./responses/500.yaml

data/lib/textualize/templates/new/apis/resourceTypes/collection-item-ro.yaml

@@ -0,0 +1,20 @@
+collection-item-ro:
+  description: Read only entity representing a <<resourcePathName|!singularize>>
+
+  get:
+    securedBy: [ oauth_2_0: { scopes: [ "customer", "staff" ] } ]
+    description: Get the <<resourcePathName|!singularize>> by ID
+    responses:
+      200: !include ../responses/200.yaml
+
+  patch:
+    securedBy: [ oauth_2_0: { scopes: [ "staff" ] } ]
+    description: Update the <<resourcePathName|!singularize>> by ID
+    responses:
+      204: !include ../responses/204.yaml
+
+  delete:
+    securedBy: [ oauth_2_0: { scopes: [ "staff" ] } ]
+    description: Remove the <<resourcePathName|!singularize>> by ID
+    responses:
+      204: !include ../responses/204.yaml

data/lib/textualize/templates/new/apis/resourceTypes/collection-item.yaml

@@ -0,0 +1,20 @@
+collection-item:
+  description: Entity representing a <<resourcePathName|!singularize>>
+
+  get:
+    securedBy: [ oauth_2_0: { scopes: [ "customer", "staff" ] } ]
+    description: Get the <<resourcePathName|!singularize>> by ID
+    responses:
+      200: !include ../responses/200.yaml
+
+  patch:
+    securedBy: [ oauth_2_0: { scopes: [ "customer", "staff" ] } ]
+    description: Update the <<resourcePathName|!singularize>> by ID
+    responses:
+      204: !include ../responses/204.yaml
+
+  delete:
+    securedBy: [ oauth_2_0: { scopes: [ "customer", "staff" ] } ]
+    description: Remove the <<resourcePathName|!singularize>> by ID
+    responses:
+      204: !include ../responses/204.yaml

data/lib/textualize/templates/new/apis/resourceTypes/collection-ro.yaml

@@ -0,0 +1,18 @@
+collection-ro:
+  description: Read-only collection of available <<resourcePathName>>
+
+  get:
+    securedBy: [ oauth_2_0: { scopes: [ "staff" ] } ]
+    responses:
+      200:
+        body:
+          application/json:
+            example: <<exampleCollection>>
+
+  post:
+    securedBy: [ oauth_2_0: { scopes: [ "staff" ] } ]
+    body:
+      application/json:
+        schema: <<resourcePathName|!singularize>>
+    responses:
+      200: !include ../responses/200.yaml

data/lib/textualize/templates/new/apis/resourceTypes/collection.yaml

@@ -0,0 +1,18 @@
+collection:
+  description: Collection of available <<resourcePathName>>
+
+  get:
+    securedBy: [ oauth_2_0: { scopes: [ "customer", "staff" ] } ]
+    responses:
+      200:
+        body:
+          application/json:
+            example: <<exampleCollection>>
+
+  post:
+    securedBy: [ oauth_2_0: { scopes: [ "customer", "staff" ] } ]
+    body:
+      application/json:
+        schema: <<resourcePathName|!singularize>>
+    responses:
+      200: !include ../responses/200.yaml

data/lib/textualize/templates/new/apis/responses/200.yaml

@@ -0,0 +1,3 @@
+body:
+  application/json:
+    example: <<exampleItem>>

data/lib/textualize/templates/new/apis/responses/204.yaml

@@ -0,0 +1 @@
+description: Success (no body)

data/lib/textualize/templates/new/apis/responses/400.yaml

@@ -0,0 +1,8 @@
+body:
+  application/json:
+    example: |
+      {
+        name: [
+          "has already been taken"
+        ]
+      }

data/lib/textualize/templates/new/apis/responses/401.yaml

@@ -0,0 +1,4 @@
+body:
+  application/json:
+    example: |
+      { "message": "Unauthorized, please login" }

data/lib/textualize/templates/new/apis/responses/403.yaml

@@ -0,0 +1,4 @@
+body:
+  application/json:
+    example: |
+      { "message": "Forbidden" }

data/lib/textualize/templates/new/apis/responses/404.yaml

@@ -0,0 +1,4 @@
+body:
+  application/json:
+    example: |
+      { "message": "Not found" }

data/lib/textualize/templates/new/apis/responses/422.yaml

@@ -0,0 +1,8 @@
+body:
+  application/json:
+    example: |
+      {
+        name: [
+          "parameter is required"
+        ]
+      }

data/lib/textualize/templates/new/apis/responses/500.yaml

@@ -0,0 +1,4 @@
+body:
+  application/json:
+    example: |
+      { "message": "Server error" }

data/lib/textualize/templates/new/gulpfile.js

@@ -0,0 +1,93 @@
+var gulp = require('gulp');
+
+gulp.task('default', ['convert-raml-to-json'])
+
+gulp.task('mkdir-src', function() {
+  var mkdirp = require('mkdirp')
+
+  mkdirp('./.tmp')
+
+  return gulp.src('./')
+})
+
+var raml       = require('gulp-raml');
+var debug      = require('gulp-debug');
+
+gulp.task('validate-raml', function() {
+  return gulp.src('apis/*.raml')
+
+  .pipe(debug({title: 'checking raml file: '}))
+  .pipe(raml())
+  .pipe(raml.reporter('default'))
+  .pipe(raml.reporter('fail'))
+})
+
+var notify     = require('gulp-notify');
+var concat     = require('gulp-concat');
+var yaml       = require('gulp-yaml');
+
+gulp.task('convert-raml-to-json', ['validate-raml'], function() {
+  return gulp.src('apis/*.raml', { base: './' })
+  .pipe(raml2json())
+  .pipe(gulp.dest('./.tmp'))
+})
+
+function raml2json(options) {
+  var path = require('path');
+  var gutil = require('gulp-util');
+  var through = require('through2');
+  var raml2html = require('raml2html');
+
+  var simplifyMark = function(mark) {
+    if (mark) {
+      mark.buffer = mark.buffer.split('\n', mark.line + 1)[mark.line].trim();
+    }
+  }
+
+  var options = {}
+  options.type = 'json'
+  options.config = {
+    template: function(obj) { return JSON.stringify(obj, null, 2); }
+  };
+  options.extension = '.json'
+
+  var stream = through.obj(function(file, enc, done) {
+    var fail = function(message) {
+      done(new gutil.PluginError('raml2html', message));
+    };
+    if (file.isBuffer()) {
+      var cwd = process.cwd();
+      process.chdir(path.resolve(path.dirname(file.path)));
+      raml2html.render(file.contents, options.config,
+        function(output) {
+          process.chdir(cwd);
+          stream.push(new gutil.File({
+            base: file.base,
+            cwd: file.cwd,
+            path: gutil.replaceExtension(file.path, options.extension),
+            contents: new Buffer(output)
+          }));
+          done();
+        },
+        function(error) {
+          process.chdir(cwd);
+          simplifyMark(error.context_mark);
+          simplifyMark(error.problem_mark);
+          process.nextTick(function() {
+            fail(JSON.stringify(error, null, 2));
+          });
+        });
+    }
+    else if (file.isStream()) fail(
+      'Streams are not supported: ' + file.inspect()
+    );
+    else if (file.isNull()) fail('Input file is null: ' + file.inspect());
+  });
+
+  return stream;
+}
+
+function handleError(err) {
+  console.error(err.toString());
+  this.emit('end');
+}

data/lib/textualize/templates/new/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "api-documentation",
+  "version": "0.0.1",
+  "description": "RAML documentation and gulp tasks for test/http stub files",
+  "main": "gulpfile.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "author": "",
+  "license": "Copyright by the contributors of the master branch of this repository",
+  "bugs": {
+    "url": ""
+  },
+  "homepage": "",
+  "dependencies": {
+    "gulp": "^3.8.11",
+    "gulp-concat": "^2.5.2",
+    "gulp-data": "^1.2.0",
+    "gulp-debug": "^2.0.1",
+    "gulp-load-plugins": "^0.9.0",
+    "gulp-notify": "^2.2.0",
+    "gulp-raml": "^0.1.3",
+    "gulp-template": "^3.0.0",
+    "gulp-util": "^3.0.4",
+    "gulp-yaml": "^0.2.4",
+    "js-yaml": "^3.2.7",
+    "raml2html": "^1.6.0",
+    "through2": "^0.6.3"
+  },
+  "devDependencies": {
+    "gulp-load-plugins": "^0.9.0",
+    "require-dir": "^0.3.0"
+  }
+}

data/lib/textualize/templates/new/server/api/v1/items/get.json

@@ -0,0 +1 @@
+{"data":[{"id":"1","type":"item","created_at":"1430407103","updated_at":"1430407180","name":"Hamburger","links":{"self":"https://app.my-awesome-restaurant.com/api/v1/items/1"}},{"id":"2","type":"item","created_at":"1430407103","updated_at":"1430407180","name":"Cheese burger","links":{"self":"https://app.my-awesome-restaurant.com/api/v1/items/2"}},{"id":"3","type":"item","created_at":"1430407103","updated_at":"1430407180","name":"French Fries","links":{"self":"https://app.my-awesome-restaurant.com/api/v1/items/3"}}]}

data/lib/textualize/templates/new/server/api/v1/items/{item_id}/get.json

@@ -0,0 +1 @@
+{"data":{"id":"1","type":"item","name":"Hamburger","created_at":"1430407103","updated_at":"1430407180","links":{"self":"https://app.my-awesome-restaurant.com/api/v1/hamburger/1"}}}

data/lib/textualize/templates/new/server/api/v1/orders/get.json

@@ -0,0 +1 @@
+{"data":[{"id":"1","type":"order","created_at":"1430407203","updated_at":"1430407280","links":{"self":"https://app.my-awesome-restaurant.com/api/v1/orders/1","items":{"related":"https://app.my-awesome-restaurant.com/api/v1/orders/1/items","linkage":[{"type":"items","id":"1"},{"type":"items","id":"3"}]}}},{"id":"2","type":"order","created_at":"1430407203","updated_at":"1430407280","links":{"self":"https://app.my-awesome-restaurant.com/api/v1/orders/1","items":{"related":"https://app.my-awesome-restaurant.com/api/v1/orders/2/items","linkage":[{"type":"items","id":"2"},{"type":"items","id":"3"}]}}}],"included":{"items":{"1":{"id":1,"type":"item","created_at":"1430407103","updated_at":"1430407180","name":"Hamburger","links":{"self":"https://app.my-awesome-restaurant.com/api/v1/items/1"}},"2":{"id":2,"type":"item","created_at":"1430407103","updated_at":"1430407180","name":"Cheese burger","links":{"self":"https://app.my-awesome-restaurant.com/api/v1/items/2"}},"3":{"id":3,"type":"item","created_at":"1430407103","updated_at":"1430407180","name":"French Fries","links":{"self":"https://app.my-awesome-restaurant.com/api/v1/items/3"}}}}}

data/lib/textualize/templates/new/server/api/v1/orders/{order_id}/get.json

@@ -0,0 +1 @@
+{"data":{"id":"1","type":"order","created_at":"1430407203","updated_at":"1430407280","links":{"self":"https://app.my-awesome-restaurant.com/api/v1/orders/1","items":{"related":"https://app.my-awesome-restaurant.com/api/v1/orders/1/items","linkage":[{"type":"items","id":"1"},{"type":"items","id":"3"}]}}},"included":{"items":{"1":{"id":1,"type":"item","created_at":"1430407103","updated_at":"1430407180","name":"Hamburger","links":{"self":"https://app.my-awesome-restaurant.com/api/v1/items/1"}},"3":{"id":3,"type":"item","created_at":"1430407103","updated_at":"1430407180","name":"French Fries","links":{"self":"https://app.my-awesome-restaurant.com/api/v1/items/3"}}}}}

data/lib/textualize/templates/request_specs/get_collection-item.rb.erb

@@ -0,0 +1,16 @@
+require 'airborne'
+
+describe 'GET <%= url %>' do
+  let!(:<%= name %>) { create(:<%= name %>) }
+
+  before do
+    add_header_tokens(<%= secured_by %>)
+  end
+
+  it 'returns expected json' do
+    get "<%= url %>"
+    expect_status <%= response_code %>
+    expect_json_keys <%= body.data.keys %>
+  end
+end
+

data/lib/textualize/templates/request_specs/get_collection.rb.erb

@@ -0,0 +1,16 @@
+require 'airborne'
+
+describe 'GET <%= url %>' do
+  let!(:<%= name %>) { create_list(:<%= name %>, 3) }
+
+  before do
+    add_header_tokens(<%= secured_by %>)
+  end
+
+  it 'returns expected json' do
+    get "<%= url %>"
+    expect_status <%= response_code %>
+    expect_json_keys <%= body.data.sample.keys %>
+  end
+end
+

data/lib/textualize/templates/request_specs/post_collection.rb.erb

@@ -0,0 +1,13 @@
+require 'airborne'
+
+describe 'POST <%= url %>' do
+  before do
+    add_header_tokens(<%= secured_by %>)
+  end
+
+  it 'returns the saved record' do
+    post "<%= url %>"
+    expect_status <%= response_code %>
+  end
+end
+

data/lib/textualize/version.rb

@@ -0,0 +1,3 @@
+module Textualize
+  VERSION = '0.1.0'
+end

data/sample_item.rb

@@ -0,0 +1,43 @@
+{
+  verb: 'get',
+  url: '/api/v1/items',
+  relative_path: '/items',
+  type: 'collection-ro',
+  secured_by: ['staff'],
+  name: 'items',
+  response_code: 200,
+  body:  {
+    data:  [
+      {
+        id: '1',
+        type: 'item',
+        created_at: '1430407103',
+        updated_at: '1430407180',
+        name: 'Hamburger',
+        links: {
+          self: 'https://app.my-awesome-restaurant.com/api/v1/items/1'
+        }
+      },
+      {
+        id: '2',
+        type: 'item',
+        created_at: '1430407103',
+        updated_at: '1430407180',
+        name: 'Cheese burger',
+        links: {
+          self: 'https://app.my-awesome-restaurant.com/api/v1/items/2'
+        }
+      },
+      {
+        id: '3',
+        type: 'item',
+        created_at: '1430407103',
+        updated_at: '1430407180',
+        name: 'French Fries',
+        links: {
+          self: 'https://app.my-awesome-restaurant.com/api/v1/items/3'
+        }
+      }
+    ]
+  }
+}

data/textualize.gemspec

@@ -0,0 +1,41 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'textualize/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'textualize'
+  spec.version       = Textualize::VERSION
+  spec.authors       = ['Q-Centrix Dev Team']
+  spec.email         = ['devjobs@q-centrix.com']
+
+  spec.summary       = 'Turn Documentation into Tests and More'
+  spec.description   = <<-DESCRIPTION
+    Textualize uses RAML for documentation and comes with scripts to generate
+    template files that can be used to fulfill an implementation of your
+    documentation.
+  DESCRIPTION
+
+  spec.homepage      = 'https://github.com/q-centrix/textualize'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files`.split("\n").reject do |file|
+    file.match(%r{^(spec|features)/})
+  end
+  spec.executables   = spec.files.grep(%r{^bin/}) do |file|
+    File.basename(file)
+  end
+  spec.require_paths = ['lib']
+
+  spec.add_runtime_dependency 'thor',        '~> 0'
+  spec.add_runtime_dependency 'attr_extras', '~> 4'
+  spec.add_runtime_dependency 'hashie',      '~> 3'
+  spec.add_runtime_dependency 'uglifier',      '~> 2'
+
+  spec.add_development_dependency 'aruba',   '~> 0'
+  spec.add_development_dependency 'byebug',  '~> 3'
+  spec.add_development_dependency 'pry',     '~> 0'
+  spec.add_development_dependency 'bundler', '~> 1.8'
+  spec.add_development_dependency 'rake',    '~> 10.0'
+  spec.add_development_dependency 'rspec',   '~> 3'
+end