zero-rails_openapi 1.5.1 → 1.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8973e94b7dd3112572e08cbf838ed9d5288ae092
-  data.tar.gz: a89c1d354004e40c6441c0ede06b848111a5c8bb
+  metadata.gz: 7f7b1eb53af2017d4b4b522191cd0b59e9a69df8
+  data.tar.gz: e476592261a8979af7ce367dce37485a0b6f85e8
 SHA512:
-  metadata.gz: 170477a27cca4298664b2d95a7ac65879b79bcbd64ab42f23aaa917b0c45f61506e54c7d5027d9503ae96a04a031f0de34c1dc21cf0ad96ffd5962d98ec9916f
-  data.tar.gz: 532e6c8c37abdcd5e7d00c5f10cdedc5ceab6c2e187760a636c1dfda9b4d5b71b9aa5b6ac5d85cfca69c7b8fd3aa21de3a2ff0c2170e790104993a1317320b17
+  metadata.gz: 4022825604733ac97526339adbcd940603b12465e0cfe69fddc3317e3359d1ab019c2275e086aad688b447611baf2c51328682a2730adb79e2a1654949c60196
+  data.tar.gz: 250f949531bb8d03cc1b386b55dd4d7026ed67eeeef7fb42b42fbf778ff624819a221d2ab0b21157f429309cb6d590085e1cfea03618b8d0e7abb4a9f7bf85d0

data/CHANGELOG.md

@@ -2,7 +2,28 @@
 
 ## [Unreleased]
 
-## [1.5.1 - 100% Test Coverage] - 2017/12/21 - [view diff](https://github.com/zhandao/zero-rails_openapi/compare/v1.4.3...v1.5.0)
+## [1.5.2] - 2018/1/2 - [view diff](https://github.com/zhandao/zero-rails_openapi/compare/v1.5.1...v1.5.2)
+
+## Added
+
+1. `do_*` can be passed common schema after (or before) `by:`.
+2. when this action can be accessed through multiple HTTP methods (but not set through `match`),
+   it also matches and generate both HTTP methods.
+
+## Changed
+
+1. `root_controller` => `base_doc_class`.
+2. `ctrl_path` => `ctrl_base`.
+3. `apis_tag` => `doc_tag`.
+4. `@_ctrl_infos` => `@doc_info`, `@_api_infos` => `@api_info`, `@_apis_dry_blocks` => `@zro_dry_blocks`.
+5. `OpenApi.paths_index` => `OpenApi.routes_index`.
+6. `get_actions_by_ctrl_path` => `get_actions_by_route_base`.
+7. `Config.dft_file_format` => `Config.file_format`.
+8. Modify the description of the test case (remove `should`).
+9. `deep_merge!` instead of `_fusion`.
+10. `ApiInfoObj` => `ApiInfo`.
+
+## [1.5.1 - 100% Test Coverage] - 2017/12/21 - [view diff](https://github.com/zhandao/zero-rails_openapi/compare/v1.4.3...v1.5.1)
 
 ### Completed the test code (250+ examples), and make it 100% coverage.
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    zero-rails_openapi (1.5.1)
+    zero-rails_openapi (1.5.2)
       activesupport (>= 3)
       rails (>= 3)
 
@@ -66,7 +66,7 @@ GEM
     mini_mime (1.0.0)
     mini_portile2 (2.3.0)
     minitest (5.10.3)
-    nio4r (2.1.0)
+    nio4r (2.2.0)
     nokogiri (1.8.1)
       mini_portile2 (~> 2.3.0)
     rack (2.0.3)

data/README.md

@@ -36,7 +36,7 @@
     - [Atuo Generate index/show Actions's Responses Based on DB Schema](#trick5---auto-generate-indexshow-actionss-response-types-based-on-db-schema)
     - [Combined Schema (one_of / all_of / any_of / not)](#trick6---combined-schema-one_of--all_of--any_of--not)
 - [Troubleshooting](#troubleshooting)
-- [About `OpenApi.docs` and `OpenApi.paths_index`](#about-openapidocs-and-openapipaths_index)
+- [About `OpenApi.docs` and `OpenApi.routes_index`](#about-openapidocs-and-openapiroutes_index)
 
 ## About OAS
 
@@ -83,8 +83,8 @@
     c.open_api_docs = {
         # The definition of the document `homepage`.
         homepage: {
-            # [REQUIRED] ZRO will scan all the descendants of root_controller, then generate their docs.
-            root_controller: Api::V1::BaseController,
+            # [REQUIRED] ZRO will scan all the descendants of base_doc_class, then generate their docs.
+            base_doc_class: Api::V1::BaseController,
   
             # [REQUIRED] OAS Info Object: The section contains API information.
             info: {
@@ -112,7 +112,7 @@
   
   OpenApi::Config.tap do |c|
     c.instance_eval do
-      open_api :homepage_api, root_controller: ApiDoc
+      open_api :homepage_api, base_doc_class: ApiDoc
       info version: '1.0.0', title: 'Homepage APIs'
     end
   end
@@ -138,7 +138,7 @@
   Here is the simplest usage:
   
   ```ruby
-  class Api::V1::ExamplesController < Api::V1::BaseController
+  class Api::ExamplesController < ApiController
     api :index, 'GET list' do
       query :page, Integer#, desc: 'page, greater than 1', range: { ge: 1 }, dft: 1
       query :rows, Integer#, desc: 'per page', range: { ge: 1 }, default: 10
@@ -151,26 +151,26 @@
 
 ### DSL as class methods ([source code](lib/open_api/dsl.rb))
 
-#### (1) `ctrl_path` (controller path) [optional if you're writing DSL in controller]
+#### (1) `route_base` [optional if you're writing DSL in controller]
 
   ```ruby
   # method signature
-  ctrl_path(path)
+  route_base(path)
   # usage
-  ctrl_path 'api/v1/examples'
+  route_base 'api/v1/examples'
   ```
-  It is optional because `ctrl_path` defaults to `controller_path`.
+  It is optional because `route_base` defaults to `controller_path`.
   
-  [Here's a trick](#trick1---write-the-dsl-somewhere-else): Using `ctrl_path`, you can write the DSL somewhere else 
+  [Here's a trick](#trick1---write-the-dsl-somewhere-else): Using `route_base`, you can write the DSL somewhere else 
   to simplify the current controller.  
 
-#### (2) `apis_tag` [optional]
+#### (2) `doc_tag` [optional]
 
   ```ruby
   # method signature
-  apis_tag(name: nil, desc: '', external_doc_url: '')
+  doc_tag(name: nil, desc: '', external_doc_url: nil)
   # usage
-  apis_tag name: 'ExampleTagName', desc: 'ExamplesController\'s APIs'
+  doc_tag name: 'ExampleTagName', desc: 'ExamplesController\'s APIs'
   ```
   This method allows you to set the Tag (which is a node of [OpenApi Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#openapi-object)).  
   
@@ -640,7 +640,7 @@
   ```ruby
   # config/initializers/open_api.rb
   # in your configuration
-  root_controller: ApiDoc
+  base_doc_class: ApiDoc
   
   # app/api_doc/api_doc.rb
   require 'open_api/dsl'
@@ -651,7 +651,7 @@
   
   # app/api_doc/v1/examples_doc.rb
   class V1::ExamplesDoc < ApiDoc
-    ctrl_path 'api/v1/examples'
+    route_base 'api/v1/examples'
     
     api :index do
       # ...
@@ -750,14 +750,14 @@
   3. Put `c.rails_routes_file = 'config/routes.txt'` to your ZRO config.
 
 
-## About `OpenApi.docs` and `OpenApi.paths_index`
+## About `OpenApi.docs` and `OpenApi.routes_index`
 
   After `OpenApi.write_docs`, the above two module variables will be generated.
   
   `OpenApi.docs`: A Hash with API names as keys, and documents of each APIs as values.  
   documents are instances of ActiveSupport::HashWithIndifferentAccess.
   
-  `OpenApi.paths_index`: Inverted index of controller path to API name mappings.  
+  `OpenApi.routes_index`: Inverted index of controller path to API name mappings.  
   Like: `{ 'api/v1/examples' => :homepage_api }`  
   It's useful when you want to look up a document based on a controller and do something.
 

data/README_zh.md

@@ -13,7 +13,7 @@
 
   **这里是栈刀 = ▽ =  
   如果你在寻找能清晰书写 OAS API 文档的 DSL 工具，俺这个还挺不错的 ~  
-  你还可以复用其所[产出](#about-openapidocs-and-openapipaths_index)来写一些扩展，比如参数自动校验什么的（我有写哦）。  
+  你还可以复用其所[产出](#about-openapidocs-and-openapiroutes_index)来写一些扩展，比如参数自动校验什么的（我有写哦）。  
   有什么想法敬请 PR，谢过！
   另外，走过路过不妨来个 star？**
   
@@ -39,7 +39,7 @@
     - [基于 DB Schema 自动生成 response 的格式](#trick5---auto-generate-indexshow-actionss-response-types-based-on-db-schema)
     - [定义组合的 Schema (one_of / all_of / any_of / not)](#trick6---combined-schema-one_of--all_of--any_of--not)
 - [问题集](#troubleshooting)
-- [有关 `OpenApi.docs` 和 `OpenApi.paths_index`](#about-openapidocs-and-openapipaths_index)
+- [有关 `OpenApi.docs` 和 `OpenApi.routes_index`](#about-openapidocs-and-openapiroutes_index)
 
 ## About OAS
 
@@ -81,8 +81,8 @@
     c.open_api_docs = {
         # 对文档 `homepage` 进行定义
         homepage: {
-            # [REQUIRED] ZRO will scan all the descendants of root_controller, then generate their docs.
-            root_controller: Api::V1::BaseController,
+            # [REQUIRED] ZRO will scan all the descendants of base_doc_class, then generate their docs.
+            base_doc_class: Api::V1::BaseController,
   
             # [REQUIRED] OAS Info Object: The section contains API information.
             info: {
@@ -109,7 +109,7 @@
   
   OpenApi::Config.tap do |c|
     c.instance_eval do
-      open_api :homepage_api, root_controller: ApiDoc
+      open_api :homepage_api, base_doc_class: ApiDoc
       info version: '1.0.0', title: 'Homepage APIs'
     end
   end
@@ -135,7 +135,7 @@
   这是一个最简单的实例：
   
   ```ruby
-  class Api::V1::ExamplesController < Api::V1::BaseController
+  class Api::ExamplesController < ApiController
     api :index, 'GET list' do
       query :page, Integer#, desc: 'page, greater than 1', range: { ge: 1 }, dft: 1
       query :rows, Integer#, desc: 'per page', range: { ge: 1 }, default: 10
@@ -148,25 +148,25 @@
 
 ### 作为类方法的 DSL ([source code](lib/open_api/dsl.rb))
 
-#### (1) `ctrl_path` (controller path) [无需调用，当且仅当你是在控制器中写文档时]
+#### (1) `route_base` [无需调用，当且仅当你是在控制器中写文档时]
 
   ```ruby
   # method signature
-  ctrl_path(path)
+  route_base(path)
   # usage
-  ctrl_path 'api/v1/examples'
+  route_base 'api/v1/examples'
   ```
   其默认设定为 `controller_path`.
   
-  [这个技巧](#trick1---write-the-dsl-somewhere-else) 展示如何使用 `ctrl_path` 来让你将 DSL 写在他处（与控制器分离），来简化你的控制器。
+  [这个技巧](#trick1---write-the-dsl-somewhere-else) 展示如何使用 `route_base` 来让你将 DSL 写在他处（与控制器分离），来简化你的控制器。
 
-#### (2) `apis_tag` [optional]
+#### (2) `doc_tag` [optional]
 
   ```ruby
   # method signature
-  apis_tag(name: nil, desc: '', external_doc_url: '')
+  doc_tag(name: nil, desc: '', external_doc_url: '')
   # usage
-  apis_tag name: 'ExampleTagName', desc: 'ExamplesController\'s APIs'
+  doc_tag name: 'ExampleTagName', desc: 'ExamplesController\'s APIs'
   ```
   This method allows you to set the Tag (which is a node of [OpenApi Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#openapi-object)).  
   
@@ -617,7 +617,7 @@
   ```ruby
   # config/initializers/open_api.rb
   # in your configuration
-  root_controller: ApiDoc
+  base_doc_class: ApiDoc
   
   # app/api_doc/api_doc.rb
   require 'open_api/dsl'
@@ -628,7 +628,7 @@
   
   # app/api_doc/v1/examples_doc.rb
   class V1::ExamplesDoc < ApiDoc
-    ctrl_path 'api/v1/examples'
+    route_base 'api/v1/examples'
     
     api :index do
       # ...
@@ -727,14 +727,14 @@
   3. Put `c.rails_routes_file = 'config/routes.txt'` to your ZRO config.
 
 
-## About `OpenApi.docs` and `OpenApi.paths_index`
+## About `OpenApi.docs` and `OpenApi.routes_index`
 
   After `OpenApi.write_docs`, the above two module variables will be generated.
   
   `OpenApi.docs`: A Hash with API names as keys, and documents of each APIs as values.  
   documents are instances of ActiveSupport::HashWithIndifferentAccess.
   
-  `OpenApi.paths_index`: Inverted index of controller path to API name mappings.  
+  `OpenApi.routes_index`: Inverted index of controller path to API name mappings.  
   Like: `{ 'api/v1/examples' => :homepage_api }`  
   It's useful when you want to look up a document based on a controller and do something.
 

data/documentation/examples/auto_gen_doc.rb

@@ -11,7 +11,7 @@ module AutoGenDoc
       super
       subclass.class_eval do
         break unless self.name.match?(/sController|sDoc/)
-        ctrl_path self.name.sub('Doc', '').downcase.gsub('::', '/') if self.name.match?(/sDoc/)
+        route_base self.name.sub('Doc', '').downcase.gsub('::', '/') if self.name.match?(/sDoc/)
         open_api_dry
       end
     end
@@ -19,8 +19,8 @@ module AutoGenDoc
     private
 
     def open_api_dry
-      ctrl_path = try(:controller_path) || instance_variable_get('@_ctrl_path')
-      ::OpenApi::Generator.get_actions_by_ctrl_path(ctrl_path)&.each do |action|
+      route_base = try(:controller_path) || instance_variable_get('@route_base')
+      ::OpenApi::Generator.get_actions_by_route_base(route_base)&.each do |action|
         api_dry action do
           header! 'Token', String, desc: 'user token'
 

data/documentation/examples/examples_controller.rb

@@ -1,5 +1,5 @@
 class Api::V1::ExamplesController < Api::V1::BaseController
-  apis_tag name: 'ExampleTagName', desc: 'ExamplesController\'s APIs'
+  doc_tag name: 'ExampleTagName', desc: 'ExamplesController\'s APIs'
 
   components do
     schema :DogSchema => [ String, dft: 'doge' ]

data/documentation/examples/open_api.rb

@@ -3,7 +3,7 @@ require 'open_api'
 OpenApi::Config.tap do |c|
   # Config DSL
   c.instance_eval do
-    open_api :zero_rails, root_controller: ApiDoc
+    open_api :zero_rails, base_doc_class: ApiDoc
     info version: '0.0.1', title: 'Zero Rails APIs', description: 'API documentation of Zero-Rails Application.'
     server 'http://localhost:3000', desc: 'Main (production) server'
     server 'http://localhost:3000', desc: 'Internal staging server for testing'
@@ -21,8 +21,8 @@ OpenApi::Config.tap do |c|
   # Getting started: https://swagger.io/docs/specification/basic-structure/
   c.open_api_docs = {
       blog_api: {
-          # [REQUIRED] ZRO will scan all the descendants of the root_controller, then generate their docs.
-          root_controller: ApiController,
+          # [REQUIRED] ZRO will scan all the descendants of the base_doc_class, then generate their docs.
+          base_doc_class: ApiController,
 
           # [REQUIRED] Info Object: The info section contains API information
           info: {

data/documentation/parameter.md

@@ -20,7 +20,7 @@ int32, float, date ...
 All the types you can use as following:
   - **String, 'binary', 'base64'**
   - **Integer, Long, 'int32', 'int64', Float, Double**
-  - **File** (it will be converted to `{ type: 'string', format: Config.dft_file_format }`)
+  - **File** (it will be converted to `{ type: 'string', format: Config.file_format }`)
   - **Date, DateTime**
   - **Boolean**
   - **Array**: `Array[String]` or `[String]`

data/lib/oas_objs/combined_schema.rb

@@ -24,3 +24,19 @@ module OpenApi
     end
   end
 end
+
+__END__
+
+Inside schema:
+
+"oneOf": [
+  {
+    "$ref": "#components/schemas/DogSchema"
+  },
+  {
+    "type": "string"
+  },
+  {
+    "type": "integer"
+  }
+]

data/lib/oas_objs/helpers.rb

@@ -1,19 +1,7 @@
 module OpenApi
   module Helpers
     def fusion
-      proc { |a, b| a.merge!(b, &_fusion) }
-    end
-
-    def _fusion
-      proc do |_common_key, x, y|
-        if x.is_a?(Hash) && y.is_a?(Hash)
-          x.merge(y, &_fusion)
-        elsif x.is_a?(Array) && y.is_a?(Array)
-          x.concat(y)
-        else
-          y
-        end
-      end
+      proc { |a, b| a.deep_merge!(b) { |common_key, va, vb| common_key == :required ? va + vb : vb } }
     end
 
     def truly_present?(obj)
@@ -32,7 +20,7 @@ module OpenApi
 
     # reducx.then_merge! => for Hash
     def reducx(*values)
-      @assign = values.compact.reduce({ }, :merge).keep_if &value_present
+      @assign = values.compact.reduce({ }, :merge!).keep_if &value_present
       self
     end
 

data/lib/oas_objs/schema_obj.rb

@@ -69,7 +69,7 @@ module OpenApi
         elsif t.in? %w[ binary base64 ]
           { type: 'string', format: t }
         elsif t == 'file'
-          { type: 'string', format: Config.dft_file_format }
+          { type: 'string', format: Config.file_format }
         elsif t == 'datetime'
           { type: 'string', format: 'date-time' }
         else # other string
@@ -110,7 +110,7 @@ module OpenApi
           { minItems: min, maxItems: max }
         else
           { minLength: min, maxLength: max }
-        end.merge(enum: _enum).keep_if &value_present
+        end.merge!(enum: _enum).keep_if &value_present
       end
 
       def processed_range

data/lib/open_api.rb

@@ -6,7 +6,7 @@ require 'open_api/dsl'
 module OpenApi
   include Generator
 
-  cattr_accessor :paths_index do
+  cattr_accessor :routes_index do
     { }
   end
 

data/lib/open_api/config.rb

@@ -32,8 +32,8 @@ module OpenApi
       {
       #     # [REQUIRED] At least one doc.
       #     zero_rails: {
-      #         # [REQUIRED] ZRO will scan all the descendants of the root_controller, and then generate their docs.
-      #         root_controller: ApplicationController,
+      #         # [REQUIRED] ZRO will scan all the descendants of the base_doc_class, and then generate their docs.
+      #         base_doc_class: ApplicationController,
       #
       #         # [REQUIRED] Info Object: The info section contains API information
       #         info: {
@@ -47,7 +47,7 @@ module OpenApi
       }
     end
 
-    cattr_accessor :dft_file_format do
+    cattr_accessor :file_format do
       'binary'
     end
 

data/lib/open_api/config_dsl.rb

@@ -4,9 +4,9 @@ module OpenApi
       base.class_eval do
         module_function
 
-        def open_api name, root_controller:
+        def open_api name, base_doc_class:
           @api = name
-          open_api_docs[name] = { root_controller: root_controller }
+          open_api_docs[name] = { base_doc_class: base_doc_class }
         end
 
         def info version:, title:, desc: '', **addition
@@ -23,16 +23,16 @@ module OpenApi
         end
 
         def base_auth scheme_name, other_info = { }
-          security_scheme scheme_name, { type: 'http', scheme: 'basic' }.merge(other_info)
+          security_scheme scheme_name, { type: 'http', scheme: 'basic', **other_info }
         end
 
         def bearer_auth scheme_name, format = 'JWT', other_info = { }
-          security_scheme scheme_name, { type: 'http', scheme: 'bearer', bearerFormat: format }.merge(other_info)
+          security_scheme scheme_name, { type: 'http', scheme: 'bearer', bearerFormat: format, **other_info }
         end
 
         def api_key scheme_name, field:, in: 'header', **other_info
           _in = binding.local_variable_get(:in)
-          security_scheme scheme_name, { type: 'apiKey', name: field, in: _in }.merge(other_info)
+          security_scheme scheme_name, { type: 'apiKey', name: field, in: _in, **other_info }
         end
 
         def global_security_require scheme_name, scopes: [ ]

data/lib/open_api/dsl.rb

@@ -1,4 +1,4 @@
-require 'open_api/dsl/api_info_obj'
+require 'open_api/dsl/api_info'
 require 'open_api/dsl/components'
 
 module OpenApi
@@ -9,58 +9,59 @@ module OpenApi
 
     # TODO: Doc-Block Comments
     module ClassMethods
-      def ctrl_path path
-        @_ctrl_path = path
-        @_apis_tag  = path.split('/').last.camelize
+      def route_base path
+        @route_base = path
+        @doc_tag    = path.split('/').last.camelize
       end
 
-      def apis_tag name: nil, desc: '', external_doc_url: ''
-        # current `tag`, this means that tags is currently divided by controllers.
-        @_apis_tag = name if name.present?
-        @_apis_tag ||= controller_name.camelize
-        tag = (@_ctrl_infos = { })[:tag] = { name: @_apis_tag }
+      def doc_tag name: nil, desc: '', external_doc_url: nil
+        # apis will group by the tags.
+        @doc_tag = name if name.present?
+        @doc_tag ||= controller_name.camelize
+        tag = (@doc_info = { })[:tag] = { name: @doc_tag }
         tag[:description]  = desc if desc.present?
-        tag[:externalDocs] = { description: 'ref', url: external_doc_url } if external_doc_url.present?
+        tag[:externalDocs] = { description: 'ref', url: external_doc_url } if external_doc_url
       end
 
       def components &block
-        apis_tag if @_ctrl_infos.nil?
-        current_ctrl = @_ctrl_infos[:components] = Components.new
-        current_ctrl.instance_exec(&block)
-        current_ctrl.process_objs
+        doc_tag if @doc_info.nil?
+        current_doc = @doc_info[:components] = Components.new
+        current_doc.instance_exec(&block)
+        current_doc.process_objs
       end
 
-      def api action, summary = '', http: nil, skip: [ ], use: [ ], &block
-        apis_tag if @_ctrl_infos.nil?
+      def api action, summary = '', http: http_method = nil, skip: [ ], use: [ ], &block
+        doc_tag if @doc_info.nil?
         # select the routing info (corresponding to the current method) from routing list.
-        action_path = "#{@_ctrl_path ||= controller_path}##{action}"
-        routes_info = ctrl_routes_list&.select { |api| api[:action_path].match?(/^#{action_path}$/) }&.first
-        pp "[ZRO Warning] Routing mapping failed: #{@_ctrl_path}##{action}" and return if routes_info.nil?
+        action_path = "#{@route_base ||= controller_path}##{action}"
+        routes = ctrl_routes_list&.select { |api| api[:action_path].match?(/^#{action_path}$/) }
+        pp "[ZRO Warning] Routing mapping failed: #{@route_base}##{action}" and return if routes.blank?
 
-        api = ApiInfoObj.new(action_path, skip: Array(skip), use: Array(use))
-                        .merge! description: '', summary: summary, operationId: action, tags: [@_apis_tag],
-                                parameters: [ ], requestBody: '',  responses: { },      security: [ ], servers: [ ]
-        [action, :all].each { |blk_key| @_api_dry_blocks&.[](blk_key)&.each { |blk| api.instance_eval(&blk) } }
-        api.param_use  = [ ] # `skip` and `use` only affect `api_dry`'s blocks
-        api.param_skip = [ ]
-        api.param_use = [ ] # `skip` and `use` only affect `api_dry`'s blocks
+        api = ApiInfo.new(action_path, skip: Array(skip), use: Array(use))
+                     .merge! description: '', summary: summary, operationId: action, tags: [@doc_tag],
+                             parameters: [ ], requestBody: '',  responses: { },      security: [ ], servers: [ ]
+        [action, :all].each { |blk_key| @zro_dry_blocks&.[](blk_key)&.each { |blk| api.instance_eval(&blk) } }
+        api.param_use = api.param_skip = [ ] # `skip` and `use` only affect `api_dry`'s blocks
         api.instance_exec(&block) if block_given?
         api.process_objs
         api.delete_if { |_, v| v.blank? }
 
-        path = (@_api_infos ||= { })[routes_info[:path]] ||= { }
-        (http || routes_info[:http_verb]).split('|').each { |verb| path[verb] = api }
+        routes.each do |route|
+          path = (@api_info ||= { })[route[:path]] ||= { }
+          (http || route[:http_verb]).split('|').each { |verb| path[verb] = api }
+        end
+
         api
       end
 
       # method could be symbol array, like: %i[ .. ]
       def api_dry action = :all, desc = '', &block
-        @_api_dry_blocks ||= { }
-        Array(action).each { |a| (@_api_dry_blocks[a.to_sym] ||= [ ]) << block }
+        @zro_dry_blocks ||= { }
+        Array(action).each { |a| (@zro_dry_blocks[a.to_sym] ||= [ ]) << block }
       end
 
       def ctrl_routes_list
-        Generator.routes_list[@_ctrl_path]
+        Generator.routes_list[@route_base]
       end
     end
   end

data/lib/open_api/dsl/{api_info_obj.rb → api_info.rb}

@@ -2,7 +2,7 @@ require 'open_api/dsl/common_dsl'
 
 module OpenApi
   module DSL
-    class ApiInfoObj < Hash
+    class ApiInfo < Hash
       include DSL::CommonDSL
       include DSL::Helpers
 
@@ -57,12 +57,12 @@ module OpenApi
       #         :export! => { type: Boolean }
       #   }
       %i[ header header! path path! query query! cookie cookie! ].each do |param_type|
-        define_method "do_#{param_type}" do |by:|
-          by.each do |key, value|
+        define_method "do_#{param_type}" do |by:, **common_schema|
+          by.each do |p_name, schema|
             action = param_type.to_s.delete('!')
-            type, value = value.is_a?(Hash) ? [value[:type], value] : [value, { }]
-            args = [ key.to_s.delete('!').to_sym, type, value ]
-            param_type['!'] || key['!'] ? send("#{action}!", *args) : send(action, *args)
+            type, schema = schema.is_a?(Hash) ? [schema[:type], schema] : [schema, { }]
+            args = [ p_name.to_s.delete('!').to_sym, type, schema.reverse_merge!(common_schema) ]
+            param_type['!'] || p_name['!'] ? send("#{action}!", *args) : send(action, *args)
           end
         end
       end
@@ -75,7 +75,7 @@ module OpenApi
       def request_body required, media_type, data: { }, **options
         desc = options.delete(:desc) || ''
         self[:requestBody] = RequestBodyObj.new(required, desc) unless self[:requestBody].is_a?(RequestBodyObj)
-        self[:requestBody].add_or_fusion(media_type, options.merge(data: data))
+        self[:requestBody].add_or_fusion(media_type, { data: data , **options })
       end
 
       # [ body body! ]

data/lib/open_api/dsl/components.rb

@@ -43,7 +43,7 @@ module OpenApi
         desc = options.delete(:desc) || ''
         cur = (self[:requestBodies] ||= { })[component_key]
         cur = RequestBodyObj.new(required, desc) unless cur.is_a?(RequestBodyObj)
-        self[:requestBodies][component_key] = cur.add_or_fusion(media_type, options.merge(data: data))
+        self[:requestBodies][component_key] = cur.add_or_fusion(media_type, { data: data, **options })
       end
 
       # [ body body! ]
@@ -65,18 +65,18 @@ module OpenApi
       alias auth_scheme security_scheme
 
       def base_auth scheme_name, other_info = { }
-        security_scheme scheme_name, { type: 'http', scheme: 'basic' }.merge(other_info)
+        security_scheme scheme_name, { type: 'http', scheme: 'basic', **other_info }
       end
       arrow_enable :base_auth
 
       def bearer_auth scheme_name, format = 'JWT', other_info = { }
-        security_scheme scheme_name, { type: 'http', scheme: 'bearer', bearerFormat: format }.merge(other_info)
+        security_scheme scheme_name, { type: 'http', scheme: 'bearer', bearerFormat: format, **other_info }
       end
       arrow_enable :bearer_auth
 
       def api_key scheme_name, field:, in: 'header', **other_info
         _in = binding.local_variable_get(:in)
-        security_scheme scheme_name, { type: 'apiKey', name: field, in: _in }.merge(other_info)
+        security_scheme scheme_name, { type: 'apiKey', name: field, in: _in, **other_info }
       end
       arrow_enable :api_key
 

data/lib/open_api/dsl/helpers.rb

@@ -16,7 +16,7 @@ module OpenApi
           _load_schema_based_on_show_attr(model)
         else
           model.columns.map { |column| _type_mapping(column) }
-        end.compact.reduce({ }, :merge) rescue ''
+        end.compact.reduce({ }, :merge!) rescue ''
       end
 
       def _type_mapping(column)

data/lib/open_api/generator.rb

@@ -1,7 +1,10 @@
+require 'active_support/hash_with_indifferent_access'
 require 'open_api/config'
 
 module OpenApi
   module Generator
+    extend self
+
     def self.included(base)
       base.extend ClassMethods
     end
@@ -18,31 +21,33 @@ module OpenApi
           # :nocov:
         end
         Dir[*Array(Config.doc_location)].each { |file| require file }
-        (doc_name || Config.docs.keys).map { |name| { name => generate_doc(name) } }.reduce({ }, :merge)
+        (doc_name || Config.docs.keys).map { |name| { name => generate_doc(name) } }.reduce({ }, :merge!)
       end
 
       def generate_doc(doc_name)
         settings = Config.docs[doc_name]
-        doc = { openapi: '3.0.0' }.merge(settings.slice :info, :servers).merge(
+        doc = { openapi: '3.0.0', **settings.slice(:info, :servers) }.merge!(
                 security: settings[:global_security], tags: [ ], paths: { },
                 components: {
                     securitySchemes: { }, schemas: { }, parameters: { }, requestBodies: { }
-                }.merge(settings[:components] || { })
+                }.merge!(settings[:components] || { })
               )
 
-        settings[:root_controller].descendants.each do |ctrl|
-          ctrl_infos = ctrl.instance_variable_get('@_ctrl_infos')
-          next if ctrl_infos.nil?
-          doc[:paths].merge! ctrl.instance_variable_get('@_api_infos') || { }
-          doc[:tags] << ctrl_infos[:tag]
-          doc[:components].merge!(ctrl_infos[:components] || { }) { |_key, l, r| l.merge(r) }
-          OpenApi.paths_index[ctrl.instance_variable_get('@_ctrl_path')] = doc_name
+        settings[:base_doc_class].descendants.each do |ctrl|
+          doc_info = ctrl.instance_variable_get('@doc_info')
+          next if doc_info.nil?
+
+          doc[:paths].merge!(ctrl.instance_variable_get('@api_info') || { })
+          doc[:tags] << doc_info[:tag]
+          doc[:components].deep_merge!(doc_info[:components] || { })
+          OpenApi.routes_index[ctrl.instance_variable_get('@route_base')] = doc_name
         end
+
         doc[:components].delete_if { |_, v| v.blank? }
         doc[:tags]  = doc[:tags].sort { |a, b| a[:name] <=> b[:name] }
         doc[:paths] = doc[:paths].sort.to_h
 
-        OpenApi.docs[doc_name] = ActiveSupport::HashWithIndifferentAccess.new(doc.delete_if { |_, v| v.blank? })
+        OpenApi.docs[doc_name] = HashWithIndifferentAccess.new(doc.delete_if { |_, v| v.blank? })
       end
 
       def write_docs(generate_files: true)
@@ -52,30 +57,31 @@ module OpenApi
         output_path = Config.file_output_path
         FileUtils.mkdir_p output_path
         max_length = docs.keys.map(&:size).sort.last
-        # puts '[ZRO] * * * * * *'
         docs.each do |doc_name, doc|
           puts "[ZRO] `#{doc_name.to_s.rjust(max_length)}.json` has been generated."
           File.open("#{output_path}/#{doc_name}.json", 'w') { |file| file.write JSON.pretty_generate doc }
         end
         # :nocov:
       end
-    end
+    end # end of module
 
-    def self.routes_list
-      routes =
-        if (f = Config.rails_routes_file)
-          File.read(f)
-        else
-          # :nocov:
-          # ref https://github.com/rails/rails/blob/master/railties/lib/rails/tasks/routes.rake
-          require './config/routes'
-          all_routes = Rails.application.routes.routes
-          require 'action_dispatch/routing/inspector'
-          inspector = ActionDispatch::Routing::RoutesInspector.new(all_routes)
-          inspector.format(ActionDispatch::Routing::ConsoleFormatter.new, nil)
-          # :nocov:
-        end
+    def routes
+      @routes ||=
+          if (file = Config.rails_routes_file)
+            File.read(file)
+          else
+            # :nocov:
+            # ref https://github.com/rails/rails/blob/master/railties/lib/rails/tasks/routes.rake
+            require './config/routes'
+            all_routes = Rails.application.routes.routes
+            require 'action_dispatch/routing/inspector'
+            inspector = ActionDispatch::Routing::RoutesInspector.new(all_routes)
+            inspector.format(ActionDispatch::Routing::ConsoleFormatter.new, nil)
+            # :nocov:
+          end
+    end
 
+    def routes_list
       @routes_list ||= routes.split("\n").drop(1).map do |line|
         next unless line.match?('#')
         infos = line.match(/[A-Z|].*/).to_s.split(' ') # => [GET, /api/v1/examples/:id, api/v1/examples#index]
@@ -90,14 +96,14 @@ module OpenApi
       end.compact.group_by { |api| api[:action_path].split('#').first } # => { "api/v1/examples" => [..] }, group by paths
     end
 
-    def self.get_actions_by_ctrl_path(ctrl_path)
-      routes_list[ctrl_path]&.map do |action_info|
+    def get_actions_by_route_base(route_base)
+      routes_list[route_base]&.map do |action_info|
         action_info[:action_path].split('#').last
       end
     end
 
-    def self.find_path_httpverb_by(ctrl_path, action)
-      routes_list[ctrl_path]&.map do |action_info|
+    def find_path_httpverb_by(route_base, action)
+      routes_list[route_base]&.map do |action_info|
         if action_info[:action_path].split('#').last == action.to_s
           return [ action_info[:path], action_info[:http_verb].split('|').first ]
         end

data/lib/open_api/version.rb

@@ -1,3 +1,3 @@
 module OpenApi
-  VERSION = '1.5.1'
+  VERSION = '1.5.2'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zero-rails_openapi
 version: !ruby/object:Gem::Version
-  version: 1.5.1
+  version: 1.5.2
 platform: ruby
 authors:
 - zhandao
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-12-21 00:00:00.000000000 Z
+date: 2018-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -137,7 +137,7 @@ files:
 - lib/open_api/config.rb
 - lib/open_api/config_dsl.rb
 - lib/open_api/dsl.rb
-- lib/open_api/dsl/api_info_obj.rb
+- lib/open_api/dsl/api_info.rb
 - lib/open_api/dsl/common_dsl.rb
 - lib/open_api/dsl/components.rb
 - lib/open_api/dsl/helpers.rb