skeleton 0.3.3 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bc11d07464eef522de2f6495353a454b7ffc5373
-  data.tar.gz: edbbaf9c7d4af49d479690a8baa8e8fc9bb01ccb
+  metadata.gz: 9294bad43773b066e5ce9b168b882617f614d8a2
+  data.tar.gz: ff3a33117c6924c76cec5478162571f44f761c07
 SHA512:
-  metadata.gz: 3fd5c0bc49baafa724cb849bbd1ae8a0bab61e0fa6aeb715458bf91909c7f77071841a38533c1120e0b5aff4eed7d9d3f4b277993de4bf591de5e00c4d1e6583
-  data.tar.gz: f90dbc5845e73cc978acd224d0e5db77b7bf3444ddab5dc9bb51af2f3e99eb495989e4f30644b62a2d08c506311a8f613210e869c5b7661559c27a299b450f4b
+  metadata.gz: b22eccf0dbd13780cb453fe23a6c24391dd47de28786b113be1944acc7d5c0e79bc2b2889ec3e5c7d0947b1dc50472fbe28d944bdc5c2a8401e64dfe65136ad4
+  data.tar.gz: e8de75ff865e644fcd3e6966b8f541a5710fef50e3f6e95ff3f2d1d80590e36973d465717b904e55ed4c44632bda3d0e933e1b07a03cfc7c44ea79dc3be8ca3a

data/.gitignore

@@ -20,3 +20,4 @@ tmp
 *.o
 *.a
 mkmf.log
+.DS_Store

data/README.md

@@ -7,88 +7,162 @@ running code.
 
 ```ruby
 # You would put this somewhere such as config/initializers/skeleton.rb
-Skeleton.configure do |config|
-  config.define do |structure|
-    structure.host = 'api.example.com'
-    structure.base_path = '/foo'
-
-    structure.schemes = %w(https)
-    structure.consumes = %(application/json)
-    structure.produces = %(application/json)
-  end
+structure = Skeleton.build do |s|
+  s.title = 'KISSmetrics API'
+  s.version = '1.0.0'
+  s.description = 'A simply complex skeleton'
 
-  config.info do |info|
-    info.version = '1.0.6'
-    info.title = 'An Example API'
-    info.description = 'An api to interact with data'
-    info.terms_of_service = 'https://api.example.com/terms/'
-  end
+  s.terms = 'https://www.kissmetrics.com/terms'
 
-  config.contact do |contact|
-    contact.name = 'WarmWaffles'
-    contact.email = 'warmwaffles@gmail.com'
-    contact.url = 'https://github.com/warmwaffles/skeleton'
-  end
+  s.contact.name = 'KISSmetrics'
+  s.contact.email = 'support@kissmetrics.com'
+  s.contact.url = 'https://support.kissmetrics.com'
 
-  config.license do |license|
-    license.name = 'MIT'
-  end
+  s.license.name = 'KISSmetrics'
+  s.license.url = 'https://www.kissmetrics.com'
+
+  s.host = 'api.kissmetrics.com'
+  s.base_path = '/core'
+  s.scheme(:https)
+  s.consume('application/json')
+  s.produce('application/json')
 end
 ```
 
-Inside of your rails controller you would do the following
+## Defining models
 
 ```ruby
-class ApplicationController < ActionController::Base
-  include Skeleton::Helpers::ControllerHelpers
+structure.define_model('Link') do
+  describe('The link object used for api discovery')
+  required(:href,      type: 'string')
+  required(:rel,       type: 'string')
+  optional(:templated, type: 'boolean')
+  optional(:name,      type: 'string')
+end
+
+structure.define_model('Error') do
+  describe('Represents an error')
+  required(:message, type: 'string')
+  optional(:field,   type: 'string')
+  optional(:errors,  type: 'array', items: { ref: 'Error' })
+end
+
+structure.define_model('Meta') do
+  describe('The meta information regarding the request')
+  required(:status,  type: 'integer')
+  optional(:message, type: 'string')
+  optional(:errors,  type: 'array', items: { ref: 'Error' })
 end
 ```
 
-Inside a controller that you wish to document do the following
+If you wish to reference a definition from within another model, all you need to
+do is to pass a `:ref`. If you want to know more about this structure, please
+see the swagger documentation.
+
+## Defining paths
 
 ```ruby
-class AccountsController < ApplicationController
-  define_api_path('/accounts') do |path|
-    path.get do |operation|
-      operation.tag('account')
-      operation.description = 'List all of the accounts available to you'
-
-      operation.parameter(:query, 'limit') do |p|
-        p.description = 'maximum number of results to return'
-        p.type = 'integer'
-        p.format = 'int32'
-        p.required = false
-      end
-      operation.parameter(:query, 'offset') do |p|
-        p.description = 'offset within the results returned'
-        p.type = 'integer'
-        p.format = 'int32'
-        p.required = false
-      end
+skeleton.define_path('/products') do
+  get do
+    identify('list-products')
+    tag('product')
+    summarize('List products')
+    describe('List all of the products')
+
+    parameters(:query) do
+      optional(:limit,  type: 'integer', format: 'int32', default: 20, maximum: 50, minimum: 0)
+      optional(:offset, type: 'integer', format: 'int32', default: 0)
+    end
+
+    response(200, default: true) do
+      describe('Product list')
+      header('Link', type: 'string', description: 'The list of links for the resource')
+      schema(ref: 'Product')
+    end
+
+    response(403) do
+      describe('Unauthorized')
+      header('Link', type: 'string', description: 'The list of links for the resource')
+      schema(ref: 'ErrorResponse')
     end
   end
 
-  define_api_path('/accounts/{account_id}') do |path|
-    path.get do |operation|
-      operation.tag('account')
-      operation.description = 'Get an account'
-      operation.parameter(:query, 'account_id') do |p|
-        p.description = 'The account id'
-        p.type = 'string'
-        p.format = 'uuid'
-        p.required = true
-      end
+  head do
+    tag('product')
+    summarize('List products headers')
+    describe('List the headers for the products action')
+
+    parameters(:query) do
+      optional(:limit,  type: 'integer', format: 'int32', default: 20, maximum: 50, minimum: 0)
+      optional(:offset, type: 'integer', format: 'int32', default: 0)
     end
 
-    path.options do |operation|
-      operation.tag('account')
-      operation.description = 'Show available options for the account'
-      operation.parameter(:query, 'account_id') do |p|
-        p.description = 'The account id'
-        p.type = 'string'
-        p.format = 'uuid'
-        p.required = true
-      end
+    response(200, default: true) do
+      describe('Product list')
+      header('Link', type: 'string', description: 'The list of links for the resource')
+    end
+
+    response(403) do
+      describe('Unauthorized')
+      header('Link', type: 'string', description: 'The list of links for the resource')
+    end
+  end
+
+  post do
+    tag('product')
+    summarize('Create product')
+    describe('Create a product')
+
+    parameters(:body) do
+      required(:body, schema: { ref: 'NewProduct' })
+    end
+
+    response(201) do
+      describe('Product created')
+      header('Link', type: 'string', description: 'The list of links for the resource')
+      schema(ref: 'Product')
+    end
+
+    response(400) do
+      describe('Client error')
+      header('Link', type: 'string', description: 'The list of links for the resource')
+      schema(ref: 'ErrorResponse')
+    end
+
+    response(403) do
+      describe('Unauthorized')
+      header('Link', type: 'string', description: 'The list of links for the resource')
+      schema(ref: 'ErrorResponse')
+    end
+  end
+
+  options do
+    tag('product')
+    summarize('List actions for a product')
+    describe('List actions for a product')
+
+    parameters(:query) do
+      optional(:limit,  type: 'integer', format: 'int32', default: 20, maximum: 50, minimum: 0)
+      optional(:offset, type: 'integer', format: 'int32', default: 0)
+    end
+
+    response(200, default: true) do
+      describe('Product action list')
+      header('Allow', type: 'array', items: { type: 'string' }, collection_format: 'csv')
+      header('Link', type: 'string', description: 'The list of links for the resource')
+      schema(ref: 'OptionsResponse')
+    end
+
+    response(400) do
+      describe('Client error')
+      header('Link', type: 'string', description: 'The list of links for the resource')
+      schema(ref: 'ErrorResponse')
+    end
+
+    response(403) do
+      describe('Unauthorized')
+      header('Link', type: 'string', description: 'The list of links for the resource')
+      schema(ref: 'ErrorResponse')
     end
   end
 end
@@ -102,7 +176,8 @@ class DocumentationController < ApplicationController
   def swagger
     respond_to do |format|
       format.json do
-        render(json: Skeleton.config.to_swagger_json, status: 200)
+        serializer = Skeleton::Serializers::Swagger.new(my_structure)
+        render(json: MultiJson.dump(serializer.to_h), status: 200)
       end
     end
   end

data/Rakefile

@@ -2,16 +2,23 @@ require 'bundler/gem_tasks'
 
 namespace :test do
   task :env do
-    $LOAD_PATH.unshift('lib', 'spec')
+    $LOAD_PATH.unshift('lib', 'test')
   end
 
   desc 'Runs only the specs in this project'
   task :specs => [:env] do
-    Dir.glob('./spec/**/*_spec.rb') { |f| require f }
+    Dir.glob('./test/**/*_spec.rb') { |f| require f }
+  end
+
+  desc 'Runs only the test units in this project'
+  task :units => [:env] do
+    Dir.glob('./test/**/*_test.rb') { |f| require f }
   end
 
   desc 'Runs all of the tests within this project'
-  task :all => [:specs]
+  task :all => [:env] do
+    Dir.glob('./test/**/*_{spec,test}.rb') { |f| require f }
+  end
 end
 
 desc 'Runs all of the tests within this project'

data/lib/skeleton.rb

@@ -1,20 +1,16 @@
 require 'skeleton/version'
 require 'skeleton/structure'
-require 'skeleton/config'
-require 'skeleton/helpers/controller_helpers'
+require 'skeleton/serializers/swagger'
+require 'skeleton/serializers/options'
 
 module Skeleton
+  # Allows you to build a skeleton structure from within a block
+  #
+  # @return [Skeleton::Structure]
   def self.build(&block)
     structure = Skeleton::Structure.new
     yield(structure) if block
     structure
   end
-
-  def self.config
-    @config ||= Skeleton::Config.new
-  end
-
-  def self.configure(&block)
-    yield(config) if block
-  end
 end
+

data/lib/skeleton/contact.rb

@@ -1,17 +1,5 @@
-require 'skeleton/model'
-
 module Skeleton
-  class Contact < Model
+  class Contact
     attr_accessor :name, :email, :url
-    attr_presence :name, :email, :url
-
-    def to_h
-      hash = {}
-      hash[:name] = name if name?
-      hash[:email] = email if email?
-      hash[:url] = url if url?
-      hash
-    end
-    alias_method :to_swagger_hash, :to_h
   end
 end

data/lib/skeleton/error.rb

@@ -0,0 +1,4 @@
+module Skeleton
+  class Error < StandardError
+  end
+end

data/lib/skeleton/graph.rb

@@ -0,0 +1,56 @@
+require 'set'
+require 'tsort'
+
+module Skeleton
+  class Graph
+    include Enumerable
+    include TSort
+
+    def initialize
+      @dep = Hash.new { |h,k| h[k] = Set.new }
+    end
+
+    # Register a dependency
+    #
+    # @param base [Object] the base object
+    # @param list [Object,Array] list of dependents
+    def register(base, *list)
+      dependents = Array(list).flatten
+      @dep[base] ||= Set.new
+      @dep[base].merge(dependents)
+    end
+
+    # Iterate over each of the nodes in this graph with their edge
+    #
+    # @return [void]
+    def each(&block)
+      @dep.each do |base, set|
+        set.each do |name|
+          yield(base, name) if block
+        end
+      end
+    end
+
+    # Takes all of the nodes in this graph and creates a set with them
+    #
+    # @return [Set]
+    def to_set
+      set = Set.new
+      @dep.each do |base, deps|
+        set.add(base)
+        set.merge(deps)
+      end
+      set
+    end
+
+    def each_dependent_for(base, &block)
+      each_strongly_connected_component_from(base) do |dependent, _|
+        yield(dependent)
+      end
+    end
+
+    def tsort_each_child(node, &block)
+      @dep[node].each(&block)
+    end
+  end
+end

data/lib/skeleton/header.rb

@@ -1,67 +1,6 @@
-require 'skeleton/model'
+require 'skeleton/schema'
 
 module Skeleton
-  class Header < Model
-    attr_accessor :type, :format, :title, :description, :default, :multiple_of,
-                  :maximum, :exclusive_maximum, :minimum, :exclusive_minimum,
-                  :max_length, :min_length, :pattern, :max_items, :min_items,
-                  :unique_items, :max_properties, :min_properties
-
-    attr_writer :enum
-    attr_presence :exclusive_maximum, :exclusive_minimum, :unique_items
-
-    def enum
-      @enum ||= []
-    end
-
-    def enum?
-      !enum.empty?
-    end
-
-    def to_h
-      hash = {}
-      hash[:description]       = header.description       if header.description?
-      hash[:type]              = header.type              if header.type?
-      hash[:format]            = header.format            if header.format?
-      hash[:items]             = header.items             if header.items?
-      hash[:collection_format] = header.collection_format if header.collection_format?
-      hash[:default]           = header.default           if header.default?
-      hash[:maximum]           = header.maximum           if header.maximum?
-      hash[:exclusive_maximum] = header.exclusive_maximum if header.exclusive_maximum?
-      hash[:minimum]           = header.minimum           if header.minimum?
-      hash[:exclusive_minimum] = header.exclusive_minimum if header.exclusive_minimum?
-      hash[:max_length]        = header.max_length        if header.max_length?
-      hash[:min_length]        = header.min_length        if header.min_length?
-      hash[:pattern]           = header.pattern           if header.pattern?
-      hash[:max_items]         = header.max_items         if header.max_items?
-      hash[:min_items]         = header.min_items         if header.min_items?
-      hash[:unique_items]      = header.unique_items      if header.unique_items?
-      hash[:enum]              = header.enum              if header.enum?
-      hash[:multiple_of]       = header.multiple_of       if header.multiple_of?
-      hash
-    end
-
-    def to_swagger_hash
-      hash = {}
-      hash[:description]      = header.description       if header.description?
-      hash[:type]             = header.type              if header.type?
-      hash[:format]           = header.format            if header.format?
-      hash[:items]            = header.items             if header.items?
-      hash[:collectionFormat] = header.collection_format if header.collection_format?
-      hash[:default]          = header.default           if header.default?
-      hash[:maximum]          = header.maximum           if header.maximum?
-      hash[:exclusiveMaximum] = header.exclusive_maximum if header.exclusive_maximum?
-      hash[:minimum]          = header.minimum           if header.minimum?
-      hash[:exclusiveMinimum] = header.exclusive_minimum if header.exclusive_minimum?
-      hash[:maxLength]        = header.max_length        if header.max_length?
-      hash[:minLength]        = header.min_length        if header.min_length?
-      hash[:pattern]          = header.pattern           if header.pattern?
-      hash[:maxItems]         = header.max_items         if header.max_items?
-      hash[:minItems]         = header.min_items         if header.min_items?
-      hash[:uniqueItems]      = header.unique_items      if header.unique_items?
-      hash[:enum]             = header.enum              if header.enum?
-      hash[:multipleOf]       = header.multiple_of       if header.multiple_of?
-      hash
-    end
+  class Header < Schema
   end
 end