swagui 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0aeb4e82e294ab2acef6f0f905a5d5190240193d
-  data.tar.gz: 1078ce9042532e87e78ab297122723f8cc77dac8
+  metadata.gz: 2ece6a30df668aa10a6f7414e3acb9b533336385
+  data.tar.gz: 812dce9d3d9fb20f887928ea8a3205173905412e
 SHA512:
-  metadata.gz: 79b53723736615a736208b9773ef6262f612dbd9c61ed860e64ed87c5683e88de13fb3ce06996ec9e4a8175283e48359c323e95f204d137985f54b836f29b237
-  data.tar.gz: 4ff8496c3a6834ebabf898fe2c217a0cc6041eec362282ee6bf8af5b862ece69c561fdf23356001a257a40833b3ce0506f49d91cd8d26f0203c00166ab39ca67
+  metadata.gz: ac9745d126ccea6472f6adb5ac06d879ce0a0d276b6331c7f3a67a473a5f74deac6d6d6302aee290ca842cffb6dc163f3d572d22dca38a376275adcc1e7f843b
+  data.tar.gz: 208d92bf9221669eac16e35ef8bb9b268614091e31f828bef6023c4f33b9a58d69f561a9c2a1f7577c95cd4dd490b5a7cc8c58f7379d6f7c87ee48ca9151cd5b

data/Gemfile

@@ -2,3 +2,9 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in swagui.gemspec
 gemspec
+
+gem 'minitest'
+gem 'guard-jruby-minitest', '0.1.8'
+gem 'terminal-notifier-guard'
+gem 'pry'
+gem 'rack-test'

data/Guardfile

@@ -0,0 +1,10 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+interactor :simple
+guard 'jruby-minitest', :spec_paths => ["test"], :all_on_start => false do
+  watch(%r{^test/(.*)\/?test_(.*)\.rb$})
+  watch(%r{^lib/(.*/)?([^/]+)\.rb$})     { |m| "test/test_#{m[2]}.rb" }
+  watch(%r{^test/test_helper\.rb$})      { 'test' }
+end
+

data/README.md

@@ -35,6 +35,65 @@ end
 
 You will be able to access the [swagger-ui] loaded with your api documentation at `/doc` (your `url` setting) when the server starts.
 
+### doc file format
+
+`Swagui` supports three types of doc format
+
+1. JSON documents with no extension ([original swagger doc format]), such as `api-docs` and `account`.
+2. JSON documents with `.json` extension, such as `api-docs.json` and `account.json`.
+3. YAML documents. This the recommended approach as it is naturally more concise than json and also tries to be more opinionated in the following ways:
+   1. if not provided in `api-docs.yml`, the list of apis under `apis` is automatically populated by the names of all the .yml files in the same directory.
+   2. the `basePath` attribute of each doc, used for `try it out` feature, if unprovided, is automatically provided based on the host application. this assumes the doc is hosted as part of the application.
+   3. to circumvent all the rather complex and tedious syntax for `models`, schema attributes under `apis/operations/parameters` (for request body json schema) and `apis/operations/responseMessages` (for response body json schema), and it will be used to automatically populate the `models` under root.
+
+With this approach, swagger api docs are now a lot more concise and readible, let alone having dynamic `basePath`.
+
+#### sample api-docs.yml
+```yaml
+---
+  info:
+    title: "a sojourner's api"
+    description: "Ut? Amet, et eros nascetur parturient diam scelerisque, egestas, pulvinar sit cum, rhoncus eros vel urna aliquam massa! Turpis purus auctor proin aliquam nunc, nec proin vel enim est, scelerisque! Ac vel integer proin sed in."
+    contact: "sojourner@world.net"
+  apiVersion: "1.0.0"
+  swaggerVersion: "1.2"
+  authorizations: {}
+
+```
+#### sample account.yml
+```yaml
+---
+  produces:
+    - application/json
+  apis:
+    -
+      path: /account
+      description: create or update a account
+      operations:
+        -
+          method: POST
+          summary: create or update an account
+          nickname: PostAccount
+          parameters:
+            -
+              name: body
+              required: true
+              schema: test/doc/schemas/account_post_request_body.schema.json
+              paramType: body
+          responseMessages:
+            -
+              code: 200
+              message: account creation success
+              schema: test/doc/schemas/account_post_creation_success.schema.json
+            -
+              code: 400
+              message: account creation failure
+              schema: test/doc/schemas/account_post_creation_failure.schema.json
+
+```
+
+
+
 ### Command-line utility
 
 Sometimes, you only want to see the documentation without starting the entire application. All you need to do is to run the following command in your documentation directory:
@@ -48,7 +107,7 @@ optionally, you can specify the directory name as a command line argument:
 You will then able to view the [swagger-ui] loaded with your api documentation at `http://localhost:9292`
 
 [swagger-ui]: https://github.com/wordnik/swagger-ui
-
+[original swagger doc format]: https://github.com/wordnik/swagger-spec/blob/master/fixtures/v1.2/helloworld/static/api-docs
 ## Contributing
 
 1. Fork it ( https://github.com/jackxxu/swagui/fork )
@@ -56,3 +115,4 @@ You will then able to view the [swagger-ui] loaded with your api documentation a
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create a new Pull Request
+

data/Rakefile

@@ -1,2 +1,9 @@
 require "bundler/gem_tasks"
 
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end

data/lib/swagui.rb

@@ -1,4 +1,16 @@
-require "swagui/version"
-require "swagui/app"
-require "swagui/asset_handler"
-require "swagui/swagger_doc_handler"
+require 'swagui/version'
+require 'swagui/app'
+require 'swagui/asset_handler'
+require 'swagui/swagger_doc_handler'
+require 'swagui/yaml_doc_handler'
+require 'swagui/json_schema_parser'
+require 'swagui/json_schema'
+
+
+module Swagui
+
+  def self.file_full_path(relative_path)
+    File.expand_path(relative_path, Dir.pwd)
+  end
+
+end

data/lib/swagui/asset_handler.rb

@@ -4,6 +4,9 @@ module Swagui
     def initialize(path)
       @url_regex = Regexp.union(Regexp.new("^\/swagger-ui"), Regexp.new("^#{path}\/?$"))
       swagger_ui_dir = File.expand_path('../../swagger-ui', File.dirname(__FILE__))
+
+      raise "swagger ui assets directory #{swagger_ui_dir} does not exist"  unless File.directory?(swagger_ui_dir)
+
       @asset_file_server = Rack::File.new(swagger_ui_dir)
     end
 

data/lib/swagui/json_schema.rb

@@ -0,0 +1,38 @@
+module Swagui
+  class JsonSchema
+
+    attr_reader :name
+
+    def initialize(schema_hash, name)
+      @name = name
+      @schema_hash = schema_hash
+      @nested_objects = []
+
+      @schema_hash['properties'].each do |pname, pattributes|
+        if pattributes['type'] == 'object'
+          nested_object_name = "#{@name}-#{pname}"
+          @schema_hash['properties'][pname] = {'$ref' => nested_object_name }
+          @nested_objects << JsonSchema.new(pattributes, nested_object_name)
+        end
+      end
+    end
+
+    def properties
+      @schema_hash['properties']
+    end
+
+    def models
+      all_objects.map do |schema|
+        {
+          'id' => schema.name,
+          'properties' => schema.properties
+        }
+      end
+    end
+
+    def all_objects
+      ([self] + @nested_objects.map {|x| x.all_objects}).flatten
+    end
+
+  end
+end

data/lib/swagui/json_schema_parser.rb

@@ -0,0 +1,11 @@
+module Swagui
+  class JsonSchemaParser
+
+    # returns a hash of interlinked models
+    # the first one is the root
+    def self.parse(file, prefix = "")
+      schema_json = JSON.load(File.open(file).read)
+      JsonSchema.new(schema_json, prefix)
+    end
+  end
+end

data/lib/swagui/swagger_doc_handler.rb

@@ -2,8 +2,11 @@ module Swagui
   class SwaggerDocHandler
     def initialize(path, url)
       @url_regex = Regexp.new("^#{url}")
-      app_doc_dir = File.expand_path(path || url, Dir.pwd)
-      @app_file_server = Rack::File.new(app_doc_dir)
+      app_doc_dir = Swagui.file_full_path(path || url)
+
+      raise "swagger api doc directory #{app_doc_dir} does not exist" unless File.directory?(app_doc_dir)
+
+      @app_file_server = YAMLDocHandler.new(Rack::File.new(app_doc_dir))
     end
 
     def handles?(env)
@@ -13,26 +16,12 @@ module Swagui
     def call(env)
       path = env["PATH_INFO"].gsub(@url_regex, '') # root path renders index.html
 
-      response = first_valid_file_response(path) || [404, {"Content-Type"=>"application/json"}, '']
-
-      if response[2].path.end_with?('.yml') # yml response needs to be re=processed.
-        body = ''
-        response[2].each {|f| body = YAML::load(f).to_json}
-        response[2] = [body]
-        response[1].merge!("Content-Length"=> body.size.to_s)
-      end
+      first_valid_file_response = ['', '.json', '.yml'].map do |ext|
+        @app_file_server.call(env.merge('PATH_INFO' => "#{path}#{ext}", 'REQUEST_METHOD' => 'GET'))
+      end.find {|res| res[0] == 200 }
 
-      response[1].merge!("Content-Type"=>"application/json") # response is always json content
-
-      response
+      first_valid_file_response || [404, {"Content-Type"=>"application/json"}, '']
     end
 
-    private
-
-      def first_valid_file_response(path)
-        ['', '.json', '.yml'].map do |ext|
-          @app_file_server.call('PATH_INFO' => "#{path}#{ext}", 'REQUEST_METHOD' => 'GET')
-        end.find {|res| res[0] == 200 }
-      end
   end
 end

data/lib/swagui/version.rb

@@ -1,3 +1,3 @@
 module Swagui
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

data/lib/swagui/yaml_doc_handler.rb

@@ -0,0 +1,81 @@
+require 'yaml'
+
+module Swagui
+  class YAMLDocHandler
+
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      @app.call(env).tap do |response|
+
+        response[1].merge!("Content-Type"=>"application/json") # response is always json content
+
+        if yaml_response?(response) # yml response needs to be re=processed.
+          body = []
+          response[2].each do |f|
+            body << YAML::load(f).tap do |response_hash|
+              process_schemas(response_hash)
+              process_api_docs_api_listing(response_hash, response[2].path )
+              process_base_path(response_hash, response[2].path, env)
+            end.to_json
+          end
+
+          response[2] = body
+
+          response[1].merge!("Content-Length"=> body.first.size.to_s)
+        end
+      end
+    end
+
+    private
+
+      def yaml_response?(response)
+        response[2].respond_to?(:path) && response[2].path.end_with?('.yml')
+      end
+
+      def process_schemas(response_hash)
+        (response_hash['apis'] || []).each do |api_hash|
+          (api_hash['operations'] || []).each do |operations_hash|
+            (operations_hash['parameters'] || []).each do |parameters_hash|
+              if schema_file = parameters_hash.delete('schema')
+                schema_file_path = Swagui.file_full_path(schema_file)
+                schema = JsonSchemaParser.parse(schema_file_path, "#{operations_hash['nickname']}-Request")
+                schema.models.each {|m| (response_hash['models'] ||= {})[m['id']] = m }
+                parameters_hash.merge!('type' => schema.name)
+              end
+            end
+            operations_hash['responseMessages'].each do |response_messages_hash|
+              if schema_file = response_messages_hash.delete('schema')
+                schema_file_path = Swagui.file_full_path(schema_file)
+                schema = JsonSchemaParser.parse(schema_file_path, "#{operations_hash['nickname']}-Response-#{response_messages_hash['message'].gsub(' ', '-')}")
+                schema.models.each {|m| (response_hash['models'] ||= {})[m['id']] = m }
+                response_messages_hash.merge!('responseModel' => schema.name)
+              end
+            end
+          end
+        end
+      end
+
+      def process_api_docs_api_listing(response_hash, doc_path)
+        if doc_path.end_with?('api-docs.yml') && response_hash['models'].nil? # requesting the root
+          dir_path = File.dirname(doc_path)
+          files = Dir["#{File.dirname(doc_path)}/*.yml"].map {|x| x.gsub(dir_path, '').gsub('.yml', '')}
+          files.each do |file|
+            unless file == '/api-docs'
+              (response_hash['apis'] ||= []) << {'path' => "/..#{file}"}
+            end
+          end
+        end
+      end
+
+      def process_base_path(response_hash, doc_path, env)
+        if !doc_path.end_with?('api-docs.yml') && response_hash['basePath'].nil?
+          request = Rack::Request.new(env)
+          response_hash['basePath'] = (request.base_url + request.script_name)
+        end
+      end
+
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,15 @@
+require 'bundler/setup'
+require 'minitest/autorun'
+Bundler.require(:default, :test)
+
+require 'swagui'
+require 'rack/lobster'
+require 'json'
+class Minitest::Test
+  def mounted_app
+    Rack::Builder.new do
+      use Swagui::App, url: '/doc', path: 'test/doc'
+      run Rack::Lobster.new
+    end
+  end
+end

data/test/test_json_schema.rb

@@ -0,0 +1,21 @@
+require 'test_helper'
+
+class TestJsonSchema < Minitest::Test
+
+  def setup
+    sampole_schema_file = File.expand_path('doc/schemas/account_post_request_body.schema.json', File.dirname(__FILE__))
+    @schema_json = JSON.load(File.open(sampole_schema_file).read)
+  end
+
+  def test_objects_method_returns_array
+    schema = Swagui::JsonSchema.new(@schema_json, 'PostAccount')
+    assert_equal schema.all_objects.size, 2
+  end
+
+  def test_models_methods_return_array_of_hash
+    schema = Swagui::JsonSchema.new(@schema_json, 'PostAccount')
+    assert_equal schema.models.size, 2
+    assert_equal schema.models.map {|x| x['id']}, ['PostAccount', 'PostAccount-contact']
+  end
+
+end

data/test/test_json_schema_parser.rb

@@ -0,0 +1,14 @@
+require 'test_helper'
+
+class TestJsonSchemaParser < Minitest::Test
+
+  def test_parse_file
+    file_path = File.expand_path('test/doc/schemas/account_post_request_body.schema.json', Dir.pwd)
+    result = Swagui::JsonSchemaParser.parse(file_path, 'PostAccount')
+    assert_equal result.class, Swagui::JsonSchema
+    assert_equal result.name, 'PostAccount'
+    assert_equal result.models.size, 2
+    assert_equal result.models.first.class, Hash
+  end
+
+end

data/test/test_swagger_doc_handler.rb

@@ -0,0 +1,28 @@
+require 'test_helper'
+
+class TestSwaggerDocHandler < Minitest::Test
+
+  include Rack::Test::Methods
+
+  def app
+    Rack::Lint.new(mounted_app)
+  end
+
+  def test_loading_api_docs_root
+    get '/doc/api-docs'
+    assert last_response.ok?
+    response_json = JSON.parse(last_response.body)
+    assert_equal response_json['apis'].size, 1
+    assert_equal response_json['apis'].first['path'], '/../account'
+  end
+
+  def test_loading_individual_api_doc
+    get '/doc/account'
+    assert last_response.ok?
+    response_json = JSON.parse(last_response.body)
+    assert_equal response_json['apis'].size, 1
+    assert response_json['models'].size > 1
+    assert_equal response_json['models'].keys.first, 'PostAccount-Request'
+    refute response_json['basePath'].nil?
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: swagui
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Jack Xu
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2014-09-30 00:00:00.000000000 Z
+date: 2014-10-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -62,6 +62,7 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - Gemfile
+- Guardfile
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -69,8 +70,11 @@ files:
 - lib/swagui.rb
 - lib/swagui/app.rb
 - lib/swagui/asset_handler.rb
+- lib/swagui/json_schema.rb
+- lib/swagui/json_schema_parser.rb
 - lib/swagui/swagger_doc_handler.rb
 - lib/swagui/version.rb
+- lib/swagui/yaml_doc_handler.rb
 - swagger-ui/css/reset.css
 - swagger-ui/css/screen.css
 - swagger-ui/images/explorer_icons.png
@@ -95,6 +99,10 @@ files:
 - swagger-ui/swagger-ui.js
 - swagger-ui/swagger-ui.min.js
 - swagui.gemspec
+- test/test_helper.rb
+- test/test_json_schema.rb
+- test/test_json_schema_parser.rb
+- test/test_swagger_doc_handler.rb
 homepage: https://github.com/jackxxu/swagui
 licenses:
 - MIT
@@ -119,4 +127,8 @@ rubygems_version: 2.2.2
 signing_key:
 specification_version: 4
 summary: A rack-based swagger-ui middleware and commandline utility.
-test_files: []
+test_files:
+- test/test_helper.rb
+- test/test_json_schema.rb
+- test/test_json_schema_parser.rb
+- test/test_swagger_doc_handler.rb