source2swagger 0.0.1

data/.gitignore

@@ -0,0 +1 @@
+/*.gem

data/.travis.yml

@@ -0,0 +1,6 @@
+rvm:
+  - ree
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+script: rake test

data/Gemfile

@@ -0,0 +1,2 @@
+source :rubygems
+gemspec

data/LICENCE

@@ -0,0 +1,22 @@
+The MIT License
+
+Copyright (c) 2012 3scale networks S.L.
+
+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,189 @@
+
+## Description
+
+Coming soon...
+
+## Usage
+
+#### Dependencies
+
+* Ruby (1.8x or 1.9x)
+* Gem 
+* JSON gem (gem install json)
+
+#### Parameters
+
+     $ bin/source2swagger
+
+     Usage: source2swagger [options]
+     -i, --input PATH                 Directory of the input source code
+     -e, --ext ("rb"|"c"|"js"|"py")   File extension of the source code
+     -c, --comment ("##~"|"//~")      Comment tag used to write docs
+     -o, --output PATH                Directory where the json output will be saved (optional)
+
+#### Example
+
+      $ bin/souce2swagger -i ~/project/lib -e "rb" -c "##~"_
+
+This will output the Swagger compatible JSON specs on the terminal. 
+
+Add *-o /tmp* and it will write the JSON file(s) to */tmp*
+
+#### Contributions
+
+Feel free to extend the code and issue a pull request,
+
+The test suite can be invoked as
+
+      $ rake test
+
+Requires *rake* and the *gem test/unit*
+
+
+## How to
+
+Check [test/data/sample3.rb](https://github.com/solso/source2swagger/blob/master/test/data/sample3.rb) for a comprehensive real example of the *source2swagger* inline docs for Ruby.
+
+The names of the attributes can be seen on the section Grammar (partially) or better yet in the original [Swagger Specification](http://swagger.wordnik.com/spec). 
+
+#### API names declaration
+
+First you need to declare the API
+
+      ##~ a = source2swagger.namespace("your_api_spec_name")
+
+This will generate the file your_api_spec_name.json. The name can be declared in multiple files and several times in the same file. Each time *namespace* is invoked it returns the reference to the root element of the API named "your_api_spec_name".
+
+#### Setting attributes elements
+
+One by one,
+
+      ##~ a.basePath = "http://helloworld.3scale.net"
+      ##~ a.swagrVersion = "0.1a"
+      ##~ a.apiVersion = "1.0"
+
+or all at the same time,
+
+      ##~ a.set "basePath" => "http://helloworld.3scale.net", "swagrVersion" => "0.1a", "apiVersion" => "1.0"
+
+
+You can always combine
+
+      ##~ a.set "basePath" => "http://helloworld.3scale.net", "swagrVersion" => "0.1a"
+      ##~ a.apiVersion = "1.0"
+
+#### Adding and element to a list attribute
+
+      ##~ op = a.operations.add   
+      ##~ op.httpMethod = "GET"
+      ##~ op.tags = ["production"] 
+      ##~ op.nickname = "get_word"
+      ##~ deprecated => false
+      ##~
+      ##~ op = a.operations.add
+      ##~ op.set :httpMethod => "POST", :tags => ["production"], :nickname => "set_word", :deprecated => false
+  
+Two elements (*operations*) were added to *a.operations*, you can also add directly if you do not need to have a reference to the variable *op*
+
+      ##~ a.operations.add :httpMethod => "GET", :tags => ["production"], :nickname => "get_word", :deprecated => false
+      ##~ a.operations.add :httpMethod => "POST", :tags => ["production"], :nickname => "set_word", :deprecated => false
+
+#### Using variables for common structures
+
+The source2swagger notation also allows you to define variables that can be defined anywhere on the source code files as *@name = value*, the value is typically a hash structure in ruby notation (*{"key_1" => "value_1", ... , "key_n" => "value_n"}*) 
+
+*Note:* all variable declarations are evaluated before the non-variable statements so vars will always available no matter where they are defined. For instance,
+
+    ... 
+    ##  in foo.rb
+    ##~ op.parameters.add @parameter_app_id
+    ...
+    ## in bar.rb
+    ##~ @parameter_app_id = {"name" => "word", "description" => "The word whose sentiment is to be set", "dataType" => "string", "required" => true, "paramType" => "path"}
+    ...
+  
+
+#### Adding comments
+
+You can add comments on the inline docs specification, just use the normal comment tags of your language
+
+    ##~ op = a.operations.add   
+    ##
+    ##  HERE IS MY COMMENT (do not use the comment tag, e.g. ##~ but the comment tag specific of your language, in ruby #)
+    ##
+    ##~ op.httpMethod = "GET"
+
+    
+
+Check [test/data/sample3.rb](https://github.com/solso/source2swagger/blob/master/test/data/sample3.rb) for a comprehensive real example of the *source2swagger* inline docs for Ruby.
+
+
+### Grammar
+
+(partial)
+
+For a more comprehensive specification of the fields needes to declare your API on the Swagger format you can always go to the [source](http://swagger.wordnik.com/spec) 
+
+      $ROOT
+
+      a = source2swagger.namespace(STRING)
+
+      a.basepath = STRING             [required, ]
+      a.swagrVersion = STRING         []
+      a.apiVersion = STRING           []
+      a.apis = LIST[$ENDPOINTS]       [required, ]
+
+      a.models = LIST[$MODELS]        []
+
+      $ENDPOINTS
+
+      e = a.apis.add
+
+      e.path = STRING                 [required, ]
+      e.format = LIST[STRING]         [required, ]
+      e.description = STRING          [required, ]
+      e.errorResponses = LIST[$ERRORS][]
+      e.operations = LIST[$OPERATIONS][]
+
+      $OPERATIONS
+
+      o = e.operations.add
+
+      o.httpMethod = STRING           [required, ]
+      o.tags = LIST[STRING]           []
+      o.nickname = STRING             []
+      o.deprecated = BOOLEAN          []
+      o.summary = STRING              []
+      o.parameters = LIST[$PARAMETERS][]
+
+      PARAMETERS
+
+      p = o.parameters.add
+
+      p.name = STRING                 [required]
+      p.description = STRING          []
+      p.dataType = STRING             [required]
+      p.allowMultiple = BOOLEAN       []
+      p.required = BOOLEAN            []
+      p.paramType = STRING
+
+      ERRORS
+
+      err = e.operations.add
+
+      err.reason = STRING             []
+      err.code = INT                  []
+
+## Extra Resources
+
+You can edit and view the generated Swagger JSON specs online here: [JSON Editor](http://jsoneditor.appspot.com/)
+
+It's pretty basic but it works great for a quick manual inspection and edition
+of the json generated by *source2swagger*. If you know of another online editor 
+please let us know. 
+
+## License
+
+MIT License
+
+

data/Rakefile

@@ -0,0 +1,10 @@
+require 'rake/testtask'
+require 'bundler/gem_tasks'
+
+desc 'Run all unit tests'
+
+Rake::TestTask.new(:test) do |task|
+  task.test_files = FileList['test/unit/**/*_test.rb']
+  task.verbose = true
+end
+

data/bin/source2swagger

@@ -0,0 +1,84 @@
+#! /usr/bin/env ruby
+
+require 'optparse'
+require "json"
+
+begin
+  require "swagger_hash"
+  require "swagger_reader"
+rescue LoadError
+  lib = File.expand_path(File.dirname(__FILE__) + '/../lib')
+
+  if $:.include?(lib)
+    raise
+  else
+    $:.unshift(lib)
+    retry
+  end
+end
+
+opt_input = nil
+opt_output = nil
+opt_comment = nil
+opt_extension = nil
+
+parser = OptionParser.new do |parser|
+  parser.on('-i','--input PATH', 'Directory of the input source code') do |value|
+    opt_input = value
+  end
+
+  parser.on('-e','--ext ("rb"|"c"|"js"|"py")', 'File extension of the source code') do |value|
+    opt_extension = value
+  end
+
+  parser.on('-c','--comment ("##~"|"//~")','Comment tag used to write docs') do |value|
+    opt_comment = value
+  end
+
+  parser.on('-o','--output PATH','Directory where the json output will be saved (optional)') do |value|
+    opt_output = value
+  end
+
+  parser.parse!
+end
+
+unless opt_extension and opt_input and opt_comment
+  puts parser
+  abort
+end
+
+def save(results, output_path)
+  results.each do |k,v|
+    puts "  Saving API #{k} to #{output_path}/#{k}.json" 
+    File.new("#{output_path}/#{k}.json","w").puts v.to_json
+  end
+end
+
+def print(results)
+  cont = 1
+  results.each do |k,v|
+    puts "API: #{cont}, #{k}\n"
+    puts v.to_json
+    cont=cont+1
+  end
+end
+
+def run(input, extension, comment, output)
+  reader = SwaggerReader.new
+  $_swaggerhash = Hash.new
+
+  code = reader.analyze_all_files(input,extension,comment)
+  results = reader.process_code(code) unless code.nil? || code.empty?
+
+  puts "Swagger API in #{ARGV[0]}/**/*.#{ARGV[1]}: #{results.size} API\n"
+  if output.nil?
+    print(results)
+  else
+    save(results,output)
+  end
+  puts "Done!"
+
+end
+
+
+run(opt_input, opt_extension, opt_comment, opt_output)

data/lib/swagger_hash.rb

@@ -0,0 +1,70 @@
+
+class SwaggerHash < Hash
+  
+  KEEP_METHODS = %w{default []= each merge! debugger puts __id__ __send__ instance_eval == equal? initialize delegate caller object_id raise class [] to_json inspect to_s new nil?}
+  ((private_instance_methods + instance_methods).map(&:to_sym) - KEEP_METHODS.map(&:to_sym)).each{|m| undef_method(m) }
+    
+  def initialize
+    @namespaces = Hash.new
+    ##super
+  end
+
+  def namespace(name)
+    @namespaces[name] ||= SwaggerHash.new
+  end
+
+  def namespaces
+    @namespaces
+  end
+
+  def method_missing(method, *args, &block)
+
+    if method.to_s.match(/=$/)
+      self[method.to_s.gsub("=","").to_sym] = args.first
+    else
+      if self[method].nil?
+        if not method == :add
+          self[method] = SwaggerHash.new
+        else
+          if (args.nil? || args.empty?)
+            self[:_array] ||= Array.new 
+            item = SwaggerHash.new
+            self[:_array] << item
+            return item
+          else
+            self[:_array] ||= Array.new
+            args.each do |item|
+              self[:_array] << item
+            end
+          end
+        end
+      end
+      return self[method]
+    end
+  end
+  
+  def set(*args)
+    merge!(*args)  
+  end
+  
+  def to_hash
+    h2 = Hash.new
+    self.each do |k,v|
+      if v.class != SwaggerHash && v.class != Hash
+        h2[k] = v 
+      else
+        if not (v[:_array].nil?)
+          v2 = []
+          v[:_array].each do |item|
+            v2 << item.to_hash
+          end
+          h2[k] = v2
+        else
+          h2[k] = v.to_hash
+        end
+      end
+    end
+    return h2
+  end
+ 
+end

data/lib/swagger_reader.rb

@@ -0,0 +1,113 @@
+
+class SwaggerReader
+
+  def analyze_file(file, comment_str)
+
+    code = {:code => [], :line_number => [], :file =>[]}
+
+    File.open(file,"r") do |f|
+      line_number = 1
+      while (line = f.gets)
+        v = line.strip.split(" ")
+        if !v.nil? && v.size > 0 && (v[0]==comment_str)   
+          code[:code] << v[1..v.size].join(" ")
+          code[:file] << file
+          code[:line_number] << line_number
+        end
+        line_number = line_number + 1
+      end
+    end 
+
+    return code
+
+  end
+
+  def analyze_all_files(base_path, file_extension, comment_str)
+
+    code = {:code => [], :line_number => [], :file =>[]}
+
+    files = Dir["#{base_path}/**/*.#{file_extension}"].sort
+
+    files.each do |file| 
+      fcode = analyze_file(file,comment_str)
+      [:code, :line_number, :file].each do |lab|
+        code[lab] = code[lab] + fcode[lab]
+      end
+    end 
+
+    return code
+
+  end
+
+  def sort_for_vars_declaration(code)
+
+    tmp_vars = {:code => [], :line_number => [], :file =>[]}
+    tmp_not_vars = {:code => [], :line_number => [], :file =>[]}
+
+    cont = 0
+    code[:code].each do |code_line|
+      code_line.strip!        
+      if code_line[0]=='@'
+        tmp_vars[:code] << code_line.gsub('@',' ')
+        tmp_vars[:line_number] << code[:line_number][cont]
+        tmp_vars[:file] << code[:file][cont]
+      else
+        tmp_not_vars[:code] << code_line.gsub('@',' ')
+        tmp_not_vars[:line_number] << code[:line_number][cont]
+        tmp_not_vars[:file] << code[:file][cont]
+      end
+      cont=cont+1
+    end
+
+    res = {:code => tmp_vars[:code] + tmp_not_vars[:code], :line_number => tmp_vars[:line_number] + tmp_not_vars[:line_number], :file => tmp_vars[:file] + tmp_not_vars[:file]}
+
+    return res
+
+  end
+
+ 
+  def process_code(code)
+
+    code = sort_for_vars_declaration(code)
+
+    code[:code].insert(0,"source2swagger = SwaggerHash.new")
+
+    code[:code].size.times do |cont|
+      
+      begin
+        v = code[:code][0..cont]
+        v << "out = {:apis => []}"
+        v << "source2swagger.namespaces.each {|k,v| out[k] = v.to_hash}"
+        str=v.join(";")
+        proc do 
+          $SAFE = 4
+          eval(str)
+        end.call
+      rescue Exception => e
+        raise SwaggerReaderException, "Error parsing source files at #{code[:file][cont-1]}:#{code[:line_number][cont-1]}\n#{e.inspect}"
+      end
+    end
+    
+    code[:code] << "out = {:apis => []}"
+    code[:code] << "source2swagger.namespaces.each {|k,v| out[k] = v.to_hash}"
+    str = code[:code].join(";")
+    res = proc do 
+      $SAFE = 4
+      eval(str)
+    end.call
+    
+    raise SwaggerReaderException, "Error on the evaluation of the code in docs: #{res}" unless res.class==Hash
+      
+    res.each do |k, v|
+      res[k] = v.to_hash
+    end
+
+    res  
+  end
+
+end
+
+class SwaggerReaderException < Exception
+
+end
+