skeleton 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7ccc3daece70c6ebfaeb928ee50c713b1bddea5b
-  data.tar.gz: 1c4592b173ffc9e0124e1cfdf9e4783fb7444f07
+  metadata.gz: 61b5c57ad3f55a99c4f8f7b0c671d7e3bad289e2
+  data.tar.gz: 4532bd18c8c705881bce6e06660e402448dc37ad
 SHA512:
-  metadata.gz: e73b48301a296dbadfb21f3d4ab2fb7e0a33f8b8e907a0928a0e8a5f14883c9aed5613aa513b6ba72c802e3f07034c7ecb762c23daefb6e2dfa70ea6cf75168d
-  data.tar.gz: 1e92ae4c2dd11c136e75d3f5aa1d6d21fb60f910b20ab23815c5af29177f2db42e94d985629487c75e57c5674622bf1af8d5e76c99c6ca7b7308111eec1d2651
+  metadata.gz: bcfa898ec87b7a53c0c7409629222b8aa200544f72e1f10b78ad01c13e58af7ccf8d265defbecaedb1191c50156168357b34a7fec3284f9cf78e5e73e7e91ba5
+  data.tar.gz: 61969916dcf9824aa13baa48a6bcd9931ef35097afb3e40ee3a944182bad472332cf2106eea437bb6a285c9cfe84880fa705ed35d6666163e774e7560a4a0e8b

data/README.md

@@ -1,89 +1,112 @@
 # Skeleton
 
-Skeleton is a tool to help people construct `OPTIONS` api responses. This
-library is simply a data structure with no ties to any single framework.
+Was born from the desire for api documentation that can live along side actively
+running code.
 
 ## Example
 
 ```ruby
-require 'skeleton'
-
-skeleton = Skeleton.build do |config|
-  config.define(:get, also: :head) do |action|
-    action.description = 'Display a list of resources'
-
-    action.param('limit') do |p|
-      p.type = 'integer'
-      p.description = 'The number of items desired'
-      p.required = false
-      p.restriction('Minimum value is 0')
-      p.restriction('Maximum value is 9000')
-    end
+# 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
 
-    action.param('offset') do |p|
-      p.type = 'integer'
-      p.description = 'The offset within the collection'
-      p.required = false
-      p.restriction('Minimum value is 0')
-    end
+  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
 
-    action.example do |e|
-      e.param('limit', 10),
-      e.param('offset', 0)
-    end
+  config.contact do |contact|
+    contact.name = 'WarmWaffles'
+    contact.email = 'warmwaffles@gmail.com'
+    contact.url = 'https://github.com/warmwaffles/skeleton'
+  end
 
-    action.link(name: 'Self', rel: 'self', href: 'https://api.example.org/resources')
+  config.license do |license|
+    license.name = 'MIT'
   end
+end
+```
+
+Inside of your rails controller you would do the following
 
-  config.link(name: 'Documentation', rel: 'docs', href: 'https://docs.example.org/resources')
+```ruby
+class ApplicationController < ActionController::Base
+  include Skeleton::Helpers::ControllerHelpers
 end
+```
+
+Inside a controller that you wish to document do the following
 
-skeleton.to_h
+```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
+    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
+    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
+    end
+  end
+end
 ```
 
-Example `Skeleton::Builder#to_h` call
+If you want to dump the documentation to swagger you can simply do the
+following:
 
 ```ruby
-{
-  "links"=>[],
-  "GET"=>{
-    "description"=>"Display a list of resources",
-    "parameters"=>{
-      "limit"=>{
-        "type"=>"integer",
-        "description"=>"The number of items desired",
-        "required"=>false,
-        "allowed"=>[],
-        "restrictions"=>[
-          "Minimum value is 0",
-          "Maximum value is 9000"
-        ]
-      },
-      "offset"=>{
-        "type"=>"integer",
-        "description"=>"The offset within the collection",
-        "required"=>false,
-        "allowed"=>[],
-        "restrictions"=>[
-          "Minimum value is 0"
-        ]
-      }
-    },
-    "links"=>[
-      {
-        "name"=>"Self",
-        "rel"=>"self",
-        "href"=>"https://api.example.org/resources"
-      }
-    ],
-    "examples"=>[
-      {
-        "limit"=>10,
-        "offset"=>0
-      }
-    ]
-  }
-}
+class DocumentationController < ApplicationController
+  def swagger
+    respond_to do |format|
+      format.json do
+        render(json: Skeleton.config.to_swagger_json, status: 200)
+      end
+    end
+  end
+end
 ```
 
 ## Testing

data/Rakefile

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

data/lib/skeleton.rb

@@ -1,10 +1,20 @@
 require 'skeleton/version'
-require 'skeleton/builder'
+require 'skeleton/structure'
+require 'skeleton/config'
+require 'skeleton/helpers/controller_helpers'
 
 module Skeleton
   def self.build(&block)
-    builder = Builder.new
-    yield(builder) if block
-    builder
+    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/attributes.rb

@@ -0,0 +1,19 @@
+module Skeleton
+  module Attributes
+    def attr_presence(*methods)
+      Array(methods).each do |method|
+        define_method("#{method}?") do
+          !!self.public_send(method.to_s)
+        end
+      end
+    end
+
+    def attr_not_empty(*methods)
+      Array(methods).each do |method|
+        define_method("#{method}?") do
+          !self.public_send(method.to_s).empty?
+        end
+      end
+    end
+  end
+end

data/lib/skeleton/config.rb

@@ -0,0 +1,38 @@
+require 'skeleton/structure'
+require 'skeleton/serializers/swagger'
+
+module Skeleton
+  class Config
+    def structure
+      @structure ||= Skeleton::Structure.new
+    end
+
+    def info(&block)
+      yield(structure.info) if block
+    end
+
+    def define(&block)
+      yield(structure) if block
+    end
+
+    def contact(&block)
+      yield(structure.info.contact) if block
+    end
+
+    def license(&block)
+      yield(structure.info.license) if block
+    end
+
+    def path(resource, &block)
+      structure.path(resource, &block)
+    end
+
+    def parameter(location, name, &block)
+      structure.parameter(location, name, &block)
+    end
+
+    def to_swagger_json
+      structure.to_swagger_json
+    end
+  end
+end

data/lib/skeleton/contact.rb

@@ -0,0 +1,17 @@
+require 'skeleton/model'
+
+module Skeleton
+  class Contact < Model
+    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/documentation.rb

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

data/lib/skeleton/example.rb

@@ -1,17 +1,31 @@
 module Skeleton
   class Example
     def initialize
-      @params = {}
+      @mimes = {}
     end
 
-    def param(key, value)
-      p = key.to_s.downcase
-      @params[p] = value
+    def []=(mime_type, value)
+      @mimes[mime_type] = value
+    end
+
+    def [](mime_type)
+      @mimes[mime_type]
     end
 
     def to_h
-      @params
+      hash = {}
+      @mimes.each do |type, value|
+        hash[type] = value.respond_to?(:to_h) ? value.to_h : value
+      end
+      hash
+    end
+
+    def to_swagger_hash
+      hash = {}
+      @mimes.each do |type, value|
+        hash[type] = value.respond_to?(:to_h) ? value.to_swagger_hash : value
+      end
+      hash
     end
-    alias_method :to_hash, :to_h
   end
 end

data/lib/skeleton/header.rb

@@ -0,0 +1,67 @@
+require 'skeleton/model'
+
+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
+  end
+end

data/lib/skeleton/headers.rb

@@ -0,0 +1,50 @@
+require 'skeleton/model'
+require 'skeleton/header'
+
+module Skeleton
+  class Headers < Model
+    def initialize(args={})
+      @fields = {}
+      args.each { |k, v| set(k, v)}
+    end
+
+    def get(name)
+      @fields[name]
+    end
+    alias_method :[], :get
+
+    def set(name, value)
+      case value
+      when Hash
+        @fields[name] = Skeleton::Header.new(value)
+      else
+        @fields[name] = value
+      end
+    end
+    alias_method :[]=, :set
+
+    def to_h
+      hash ={}
+      @fields.each do |name, value|
+        if value.respond_to?(:to_h)
+          hash[name] = value.to_h
+        else
+          hash[name] = value
+        end
+      end
+      hash
+    end
+
+    def to_swagger_hash
+      hash ={}
+      @fields.each do |name, value|
+        if value.respond_to?(:to_swagger_hash)
+          hash[name] = value.to_swagger_hash
+        else
+          hash[name] = value
+        end
+      end
+      hash
+    end
+  end
+end