swagui 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 50e4fe6a730fae9960c9038449f113c3cfef72e6
-  data.tar.gz: f31291c54b4bea9ef5f75c3fc4d2d2de4ca30ad1
+  metadata.gz: 5ada5af68f79789855e02b8739f466125d9281d6
+  data.tar.gz: 5fab5cef417da06e01af99fbdadfb44fa87c097d
 SHA512:
-  metadata.gz: e2d25877a39a5ae885ca6ac9eaa06573b3db7b96afc7d3ef40cf369593332cda51d694a64d41e816414f49f708bcc60f89a2950a20f12674b5d6a122cdab8c87
-  data.tar.gz: ebaf37b73fe27809e2e18a35c2d60b79815f5083cef08b63b09b80a949dae586e669825acbd6981309591c281a283dfb9c07d07df89d38aff49db64c28837bf0
+  metadata.gz: 2724cf00bc4bf66c060829b45a0177c9c740d07bebeae0f97e16d45ef7153629a9cd192ec2289aed1cf819b2247eee7c77b1f187c6a27904428edb4466cc12f1
+  data.tar.gz: 551f0eda01c8fd4a8006a697d9f5693a109074d3a09ce44d4fc1b8e42adb32fe52757cfe16726b7459ceb5bf3a3603561ff906e10421a4521d01b4b8c6cf45a8

data/README.md

@@ -42,9 +42,18 @@ You will be able to access the [swagger-ui] loaded with your api documentation a
 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.
+   1. __auto listing__: 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. __auto "Try it out"__: 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. __schema-based models__: 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.
+   4. __template__: in `api-docs.yml`, a `template` section can be added that lists all the general attributes for all the apis, for example if you apis is a JSON api, chances are that they all consumes JSON requests and produces JSON responses. IN this case, instead of adding the following line in each service yml file, you can simply add this section to `api-docs.yml`.
+
+```javascript
+  template:
+    produces:
+      - application/json
+    consumes:
+      - application/json
+```
 
 With this approach, swagger api docs are now a lot more concise and readible, let alone having dynamic `basePath`.
 

data/lib/swagui/version.rb

@@ -1,3 +1,3 @@
 module Swagui
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/swagui/yaml_doc_handler.rb

@@ -5,6 +5,7 @@ module Swagui
 
     def initialize(app)
       @app = app
+      @api_json_template = nil # used to store the template settings that applies to all apis
     end
 
     def call(env)
@@ -16,8 +17,8 @@ module Swagui
           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_schemas(response_hash)
               process_base_path(response_hash, response[2].path, env)
             end.to_json
           end
@@ -51,6 +52,7 @@ module Swagui
             end
           end
         end
+        deep_merge!(response_hash, @api_json_template) if @api_json_template
       end
 
       def merge_schema!(parent_hash, response_hash, name, response_model = false)
@@ -74,6 +76,9 @@ module Swagui
 
       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
+
+          @api_json_template = response_hash.delete('template')
+
           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|
@@ -91,5 +96,19 @@ module Swagui
         end
       end
 
+      def deep_merge!(actual, template)
+        merger = proc { |key, v1, v2|
+          if (Hash === v1 && Hash === v2)
+            v1.merge!(v2, &merger)
+          elsif (Array === v2 && Array === v1)
+            v1 = v1 + v2
+          elsif (Hash === v2 && Array === v1)
+            v1.map {|x| x.merge!(v2, &merger)}
+          else
+            v1
+          end
+        }
+        actual.merge!(template, &merger)
+      end
   end
 end

data/test/doc/account.yml

@@ -1,6 +1,4 @@
 ---
-  produces:
-    - application/json
   apis:
     -
       path: /account
@@ -21,10 +19,6 @@
               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
         -
           method: GET
           summary: Get all the accounts

data/test/doc/api-docs.yml

@@ -6,3 +6,15 @@
   apiVersion: "1.0.0"
   swaggerVersion: "1.2"
   authorizations: {}
+  template:
+    produces:
+      - application/json
+    consumes:
+      - application/json
+    apis:
+      operations:
+        responseMessages:
+          -
+            code: 400
+            message: account creation failure
+            schema: test/doc/schemas/account_post_creation_failure.schema.json

data/test/test_swagger_doc_handler.rb

@@ -5,7 +5,7 @@ class TestSwaggerDocHandler < Minitest::Test
   include Rack::Test::Methods
 
   def app
-    Rack::Lint.new(mounted_app)
+    @app ||= Swagui::App.new(Rack::Lobster.new, url: '/doc', path: 'test/doc')
   end
 
   def test_loading_api_docs_root
@@ -32,4 +32,22 @@ class TestSwaggerDocHandler < Minitest::Test
     assert_equal response_json['apis'].first['operations'].last['items'], {'$ref' => 'GETAccounts'}
   end
 
+  def test_template_attributes_removed_from_api_docs
+    get '/doc/api-docs'
+    assert last_response.ok?
+    response_json = JSON.parse(last_response.body)
+    assert_nil response_json['template']
+  end
+
+  def test_template_attributes
+    get '/doc/api-docs'
+    get '/doc/account'
+    assert last_response.ok?
+    response_json = JSON.parse(last_response.body)
+    assert_equal response_json['produces'], ['application/json']
+    assert_equal response_json['consumes'], ['application/json']
+    assert_equal response_json['apis'].first['operations'].first['responseMessages'].map {|x| x['code']}, [200, 400]
+  end
+
+
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: swagui
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Jack Xu
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2014-10-15 00:00:00.000000000 Z
+date: 2014-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack