zero-rails_openapi 1.3.0 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7670c75c3357ce813ab3664c7403386a9e544c58
-  data.tar.gz: 00f1a35580391046946ce002d39ef66dad3d0a71
+  metadata.gz: 5b6fc0f663e643a98f744b0f75431c21a9484014
+  data.tar.gz: 2f0318d949040999a345d91b08f9d1ed63b525f3
 SHA512:
-  metadata.gz: e149d59f5e44dcf5349f980debf0f000345a3bf398fe9084dda7733305af6a99c42b9aed21f2fc87eabda030ca8e24e0c423a10e8ab2617296ad136dd60bea53
-  data.tar.gz: 12e6d7ad092fda104aa439dcf17c64bcb93d5a0e9467c1e5b4a27802d0ff21dc0c4a63c99523958f7bea7f174a877e43a04c0b5d1aad1f446343eb2e46e9a514
+  metadata.gz: 2e9a713e9bb2296ffb3bd9e0c5433256cf90ccf72135c92495d4eebb53778e53a151b6882bf47baf137c2b000b40fc181974f5cfa0dce45048665be7f05f29b4
+  data.tar.gz: 1691cb0d3d6e3e6517f6439ca869a7eeddf7032f6d3c9eb3118e446ac62a8d1e89da05d90cbfda7b5f32a63c70e4601749b11686b1c430664af8fd7426d1b74b

data/Gemfile

@@ -3,4 +3,8 @@ source "https://rubygems.org"
 git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
 
 # Specify your gem's dependencies in zero-rails_openapi.gemspec
-gemspec
+gemspec
+
+ruby '>= 2.3.0'
+
+gem 'activesupport'

data/Gemfile.lock

@@ -1,12 +1,21 @@
 PATH
   remote: .
   specs:
-    zero-rails_openapi (1.3.0)
+    zero-rails_openapi (1.3.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    activesupport (5.1.4)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (~> 0.7)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+    concurrent-ruby (1.0.5)
     diff-lcs (1.3)
+    i18n (0.9.0)
+      concurrent-ruby (~> 1.0)
+    minitest (5.10.3)
     rake (10.5.0)
     rspec (3.6.0)
       rspec-core (~> 3.6.0)
@@ -21,15 +30,22 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.6.0)
     rspec-support (3.6.0)
+    thread_safe (0.3.6)
+    tzinfo (1.2.4)
+      thread_safe (~> 0.1)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
+  activesupport
   bundler (~> 1.16.a)
   rake (~> 10.0)
   rspec (~> 3.0)
   zero-rails_openapi!
 
+RUBY VERSION
+   ruby 2.4.1p111
+
 BUNDLED WITH
    1.16.0.pre.2

data/README.md

@@ -29,7 +29,7 @@ but I dont have enough time now = ▽ =
     - [Global DRYing](#trick2---global-drying)
     - [Auto generate description](#trick3---auto-generate-description)
     - [Skip or Use parameters define in api_dry](#trick4---skip-or-use-parameters-define-in-api_dry)
-    - [Atuo Generate index/show Actions's Responses Based on DB Schema](#trick5)
+    - [Atuo Generate index/show Actions's Responses Based on DB Schema](#trick5---auto-generate-indexshow-actionss-responses-based-on-db-schema)
 - [Troubleshooting](#troubleshooting)
 
 ## About OAS
@@ -96,7 +96,7 @@ end
 You can also set the *global configuration(/component)* of OAS: 
 Server Object / Security Scheme Object / Security Requirement Object ...
 
-For more detailed configuration: [open_api.rb](https://github.com/zhandao/zero-rails_openapi/blob//examples/open_api.rb)
+For more detailed configuration: [open_api.rb](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/examples/open_api.rb)
 
 ## Usage
 
@@ -106,19 +106,19 @@ For more detailed configuration: [open_api.rb](https://github.com/zhandao/zero-r
 
 ```ruby
 # application_controller.rb
-require 'open_api/dsl'
-
 class ApplicationController < ActionController::API
   include OpenApi::DSL
  end
 ```
 
-#### \> [DSL Usage Example](https://github.com/zhandao/zero-rails_openapi/blob/masterdocumentation/examples/examples_controller.rb)
+#### \> [DSL Usage Example](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/examples/examples_controller.rb)
 
 (TODO: I consider that, here should be put in a the simplest case.)
 ```ruby
 class Api::V1::ExamplesController < Api::V1::BaseController
-  apis_set 'ExamplesController\'s APIs' do
+  apis_tag name: 'ExampleTagName', desc: 'ExamplesController\'s APIs'
+  
+  components do
     schema :Dog           => [ String, must_be: 'doge' ]
     query! :QueryCompUuid => [ :product_uuid, String, desc: 'product uuid' ]
     path!  :PathCompId    => [ :id, Integer, desc: 'user id' ]
@@ -169,22 +169,33 @@ end
   ctrl_path 'api/v1/examples'
   ```
   This option 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)).  
-  [Here's a trick](#write-the-dsl-somewhere-else-recommend): Using `ctrl_path`, you can write the DSL somewhere else 
+  [Here's a trick](#trick1---write-the-dsl-somewhere-else): Using `ctrl_path`, you can write the DSL somewhere else 
   to simplify the current controller.  
   \* take the tag from `path.split('/').last`
 
-- `apis_set` [Optional]
+- `apis_tag` [Optional]
 
   ```ruby
   # method signature
-  apis_set desc = '', external_doc_url = '', &block
+  apis_tag name: nil, desc: '', external_doc_url: ''
   # usage
-  apis_set 'ExamplesController\'s APIs' do
+  apis_tag name: 'ExampleTagName', desc: 'ExamplesController\'s APIs'
+  ```
+  desc and external_doc_url will be output to the tags[the current tag] (tag defaults to controller_name ), but are optional. 
+
+- `components` [Optional]
+
+  ```ruby
+  # method signature
+  components &block
+  # usage
+  components do
     # DSL for defining components
+    schema :Dog => [ String, dft: { id: 1, name: 'pet' } ]
   end
   ```
-  desc and external_doc_url will be output to the tags[the current tag] (tag defaults to controller_name ), but are optional. 
-  the focus is on the block, the DSL methods in the block will generate components.
+  Component can be used to simplify your DSL code in `*_ref` methods.  
+  Each RefObj you define is associated with components through component key.
 
 - `api_dry` [Optional]
 
@@ -207,15 +218,15 @@ end
   
   ```ruby
   # method signature
-  open_api method, summary = '', options = { }, &block
+  open_api method, summary = '', builder: nil, skip: [ ], use: [ ], &block
   # usage
-  open_api :index, '(SUMMARY) this api blah blah ...', builder: template1 do end
+  open_api :index, '(SUMMARY) this api blah blah ...', builder: :template1 do end
   ```
-  If pass `builder` or `bd` to the third parameter,
-  and `generate_jbuilder_file` in your setting file is set `true`,
+  If pass `builder` to the third parameter,
+  and `generate_jbuilder_file` is set `true` in your initializer file,
   ZRO will generate JBuilder file by using specified template that you set
   `template1` in your setting file.  
-  For example, see: [open_api.rb](https://github.com/zhandao/zero-rails_openapi/blob//examples/open_api.rb)
+  You can see: [open_api.rb](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/examples/open_api.rb)
 
 
 #### \>\> DSL methods inside *open_api* and *api_dry*'s block ([source code](https://github.com/zhandao/zero-rails_openapi/blob/master/lib/open_api/dsl_inside_block.rb):: ApiInfoObj)
@@ -241,7 +252,7 @@ parameters, request body, responses, securities, servers.
 
   ```ruby
   # method signature
-  desc desc, inputs_descs = { }
+  desc desc, param_descs = { }
   # usage
   desc 'current API\'s description',
        id:         'user id',
@@ -257,7 +268,8 @@ parameters, request body, responses, securities, servers.
   - `param`
   - `param_ref`
   - `header`, `path`, `query`, `cookie` and bang methods: `header!`, `path!`, `query!`, `cookie!`  
-  **The bang method(`!`) means it is required, so it is optional without `!`, the same below.**
+  - `do_* by: { }`  
+  **The bang method(`!`) means it is required, so without `!` means it is optional. the same below.**
 
   Define the parameters for the API(operation).
   You can use the Reference Object to link to parameters that are defined at the components/parameters by method param_ref().
@@ -266,24 +278,35 @@ parameters, request body, responses, securities, servers.
   # method signature
   param param_type, name, type, required, schema_hash = { }
   # usage
-  param :query,    :page, Integer, :req,  range: { gt: 0, le: 5 }, desc: 'page'
+  param :query, :page, Integer, :req,  range: { gt: 0, le: 5 }, desc: 'page'
   
   # method signature
   param_ref component_key, *component_keys
   # usage
   param_ref :PathCompId
-  param_ref :PathCompId, :QueryCompUuid, ...
+  param_ref :PathCompId, :QueryComp#, ...
   
   # method signature
   header  name, type, schema_hash = { }
   header! name, type, schema_hash = { }
   query!  name, type, schema_hash = { }
   # usage
-  header! :'Token', String
-  query!  :done,      Boolean, must_be: false, default: true
+  header! 'Token', String
+  query!  :read,   Boolean, must_be: true, default: false
+
+  # method signature
+  do_query by:
+  # usage
+  do_query by: {
+    :search_type => { type: String  },
+        :export! => { type: Boolean }
+  }
+  # Same as below, but a little more succinctly
+  query  :search_type, String
+  query! :export, Boolean
   ```
 
-  [**>> More About Param DSL <<**](https://github.com/zhandao/zero-rails_openapi/blob//parameter.md)
+  [**>> More About Param DSL <<**](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/parameter.md)
 
 - request_body family methods (OAS - [Request Body Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#requestBodyObject))
   - `request_body`
@@ -307,7 +330,7 @@ parameters, request body, responses, securities, servers.
   body_ref :Body
 
   # method signature
-  body(!) media_type, desc = '', schema_hash = { }
+  body! media_type, desc = '', schema_hash = { }
   # usage
   body :json
   
@@ -369,7 +392,7 @@ parameters, request body, responses, securities, servers.
 
 - server: TODO
   
-#### \>\> DSL methods inside apis_set'block ([code source](https://github.com/zhandao/zero-rails_openapi/blob/master/lib/open_api/dsl_inside_block.rb):: CtrlInfoObj )
+#### \>\> DSL methods inside components'block ([code source](https://github.com/zhandao/zero-rails_openapi/blob/master/lib/open_api/dsl_inside_block.rb):: CtrlInfoObj )
 
 (Here corresponds to OAS [Components Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#componentsObject))
 
@@ -409,7 +432,7 @@ The DSL methods used to generate the components in this block are:
   # or (unrecommended)
   schema :Dog, { id!: Integer, name: String }, dft: { id: 1, name: 'pet' }
   ```
-  *: see: [Type](https://github.com/zhandao/zero-rails_openapi/blob//parameter.md#type)
+  *: see: [Type](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/parameter.md#type)
 
 ### Generate JSON Documentation File
 
@@ -465,7 +488,7 @@ Notes: convention is the file name ends with `_doc.rb`
 
 Method `api_dry` is for DRY but its scope is limited to the current controller.
 
-I have no idea of best practices, But you can look at this [file](https://github.com/zhandao/zero-rails_openapi/blob/masterdocumentation/examples/auto_gen_doc.rb).  
+I have no idea of best practices, But you can look at this [file](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/examples/auto_gen_doc.rb).  
 The implementation of the file is: do `api_dry` when inherits the base controller inside `inherited` method.
 
 #### Trick3 - Auto Generate Description
@@ -485,7 +508,7 @@ Notice `!` use (`search_type!`, `desc!`), it tells ZRO to append
 information that analyzed from definitions (enum, must_be ..) to description automatically.
 
 Any one of above will generate:  
-`search field, allows：<br/>1/ name<br/>2/ creator,<br/>3/ category<br/>4/ price<br/>`
+> search field, allows：<br/>1/ name<br/>2/ creator,<br/>3/ category<br/>4/ price<br/>
 
 ZRO also allows you use Hash to define `enum`:
 ```ruby
@@ -497,7 +520,7 @@ query :view, String, enum: {
         'cheap goods':         :borrow,
     }
 ```
-Read this [file](https://github.com/zhandao/zero-rails_openapi/blob/examples/auto_gen_desc.rb) to learn more.
+Read this [file](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/examples/auto_gen_desc.rb) to learn more.
 
 #### Trick4 - Skip or Use parameters define in api_dry
 
@@ -506,13 +529,13 @@ Pass `skip: []` and `use: []` to `open_api` like following code:
 open_api :index, 'desc', builder: :index, skip: [ :Token ]
 ```
 
-Look at this [file](https://github.com/zhandao/zero-rails_openapi/blob/examples/goods_doc.rb) to learn more.
+Look at this [file](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/examples/goods_doc.rb) to learn more.
 
-#### Trick5 - Auto Generate index/show Actions's Responses Based on DB Schema
+#### Trick5 - Auto Generate index/show Actions's Response-Types Based on DB Schema
 
 Use method `load_schema` in `api_dry`.
 
-See this [file](https://github.com/zhandao/zero-rails_openapi/blob/examples/auto_gen_doc.rb#L51) for uasge information.
+See this [file](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/examples/auto_gen_doc.rb#L51) for uasge information.
 
 
 ## Troubleshooting

data/documentation/examples/auto_gen_doc.rb

@@ -22,7 +22,7 @@ module AutoGenDoc
       ctrl_path = try(:controller_path) || instance_variable_get('@_ctrl_path')
       ::OpenApi::Generator.get_actions_by_ctrl_path(ctrl_path)&.each do |action|
         api_dry action do
-          header! :Token, String, desc: 'user token'
+          header! 'Token', String, desc: 'user token'
 
           # Common :index parameters
           if action == 'index'
@@ -73,9 +73,8 @@ module AutoGenDoc
           # # api/v1/examples#index => ExamplesError
           # error_class_name = action_path.split('#').first.split('/').last.camelize.concat('Error')
           # error_class = Object.const_get(error_class_name) rescue next
-          # errors = error_class.errors
-          # cur_errs = (errors[action.to_sym] || []) + (errors[:private] || [ ]) + (errors[:_public] || [ ])
-          # cur_errs.each do |error|
+          # cur_api_errs = error_class.errors.values_at(action.to_sym, :private, :_public).flatten.compact.uniq
+          # cur_api_errs.each do |error|
           #   info = error_class.send(error, :info)
           #   response info[:code], info[:msg]
           # end

data/documentation/examples/examples_controller.rb

@@ -1,5 +1,7 @@
 class Api::V1::ExamplesController < Api::V1::BaseController
-  apis_set 'ExamplesController\'s APIs' do
+  apis_tag name: 'ExampleTagName', desc: 'ExamplesController\'s APIs'
+
+  components do
     schema :Dog => [{
                          id!: Integer,
                          name: { type: String, must_be: 'zhandao', desc: 'name' }

data/documentation/examples/goods_doc.rb

@@ -1,7 +1,7 @@
 class V2::GoodsDoc < BaseDoc
 
   open_api :index, 'Get list of Goods.', builder: :index,
-           use: [ :Token ] do # use parameters write in AutoGenDoc#api_dry
+           use: [ 'Token' ] do # use parameters write in AutoGenDoc#api_dry
            # skip: %i[ Token ] do # you can also skip parameters
     desc 'listing Goods',
          view!: 'search view, allows:：<br/>',
@@ -18,7 +18,7 @@ class V2::GoodsDoc < BaseDoc
   end
 
 
-  open_api :create, 'Create a Good', builder: :success_or_not, use: token do
+  open_api :create, 'Create a Good', builder: :success_or_not, use: 'Token' do
     form! 'for creating a good', data: {
                :name! => { type: String,  desc: 'good\'s name' },
         :category_id! => { type: Integer, desc: 'sub_category\'s id', npmt: true, range: { ge: 1 }, as: :cate  },
@@ -31,8 +31,8 @@ class V2::GoodsDoc < BaseDoc
   end
 
 
-  open_api :show, 'Show a Good.', builder: :show, use: [ :Token, :id ]
+  open_api :show, 'Show a Good.', builder: :show, use: [ 'Token', :id ]
 
 
-  open_api :destroy, 'Delete a Good.', builder: :success_or_not, use: [ :Token, :id ]
+  open_api :destroy, 'Delete a Good.', builder: :success_or_not, use: [ 'Token', :id ]
 end

data/documentation/examples/open_api.rb

@@ -87,45 +87,49 @@ OpenApi::Config.tap do |c|
   c.overwrite_jbuilder_file = false
   c.jbuilder_templates = {
       index: (
-      <<-FILE
-json.partial! 'api/base', total: @data.count
-
-json.data do
-  # @data = @data.page(@_page).per(@_rows) if @_page || @_rows
-  # json.array! @data do |datum|
-  json.array! @data.page(@_page).per(@_rows) do |datum|
-    json.(datum, *datum.show_attrs) if datum.present?
-  end
-end
+      <<~FILE
+        # *** Generated by ZRO ***
+        json.partial! 'api/base', total: @data.size
+        
+        json.data do
+          # @data = @data.page(@_page).per(@_rows) if @_page || @_rows
+          # json.array! @data do |datum|
+          json.array! @data.page(@_page).per(@_rows) do |datum|
+            json.(datum, *datum.show_attrs) if datum.present?
+          end
+        end
       FILE
       ),
 
       show: (
-      <<-FILE
-json.partial! 'api/base', total: 1
-
-json.data do
-  json.array! [ @data ] do |datum|
-    json.(datum, *datum.show_attrs) if datum.present?
-  end
-end
+      <<~FILE
+        # *** Generated by ZRO ***
+        json.partial! 'api/base', total: 1
+        
+        json.data do
+          json.array! [ @data ] do |datum|
+            json.(datum, *datum.show_attrs) if datum.present?
+          end
+        end
       FILE
       ),
 
       success: (
-      <<-FILE
-json.partial! 'api/success'
+      <<~FILE
+        # *** Generated by ZRO ***
+        json.partial! 'api/success'
       FILE
       ),
 
       success_or_not: (
-      <<-FILE
-unless @status
-  # @_code, @_msg = @error_info.present? ? @error_info : ApiError.action_failed.info
-end
-
-json.partial! 'api/base', total: 0
-json.data ''
+      <<~FILE
+        # *** Generated by ZRO ***
+        unless @status
+          # @_code, @_msg = @error_info.present? ? @error_info : ApiError.action_failed.info
+        end
+        
+        json.partial! 'api/base', total: 0
+        json.data ''
       FILE
       ),
   }
@@ -134,4 +138,4 @@ end
 
 Object.const_set('Boolean', 'boolean') # Support `Boolean` writing in DSL
 
-OpenApi.write_docs # Generate doc when Rails initializing
+OpenApi.write_docs generate_files: !Rails.env.production?

data/lib/oas_objs/response_obj.rb

@@ -8,7 +8,9 @@ module OpenApi
       include Helpers
 
       attr_accessor :processed, :code, :media_type
-      def initialize(code, desc, media_type, schema_hash)
+      def initialize(desc, media_type, schema_hash)
+        @schema_hash = schema_hash
+        @mt = media_type
         self.code       = code.to_s
         self.media_type = MediaTypeObj.new(media_type, schema_hash)
         self.processed  = { description: desc }
@@ -16,7 +18,13 @@ module OpenApi
 
       def process
         assign(media_type.process).to_processed 'content'
-        { code => processed }
+        processed
+      end
+
+      def override type_hash
+        @schema_hash[:type].merge!(type_hash)
+        self.media_type = MediaTypeObj.new(@mt, @schema_hash)
+        self
       end
     end
   end

data/lib/oas_objs/schema_obj.rb

@@ -40,7 +40,7 @@ module OpenApi
 
         reduceee(processed_desc options).then_merge!
       end
-      alias_method :process, :process_for
+      alias process process_for
 
       def preprocess_with_desc desc, param_name = nil
         self.__desc = desc
@@ -109,7 +109,7 @@ module OpenApi
         }
         t.each do |prop_name, prop_type|
           @prop_name = prop_name
-          _schema[:required] << "#{prop_name}".delete('!') if "#{prop_name}".match? '!'
+          _schema[:required] << "#{prop_name}".delete('!') if prop_name['!']
           _schema[:properties]["#{prop_name}".delete('!').to_sym] = recursive_obj_type prop_type
         end
         _schema.keep_if &value_present

data/lib/open_api/config.rb

@@ -1,5 +1,9 @@
+require 'open_api/config_dsl'
+
 module OpenApi
   module Config
+    include ConfigDSL
+
     # [REQUIRED] The location where .json doc file will be output.
     cattr_accessor :file_output_path do
       'public/open_api'
@@ -49,45 +53,49 @@ module OpenApi
     cattr_accessor :jbuilder_templates do
       {
           index: (
-          <<-FILE
-json.partial! 'api/base', total: @data.count
-
-json.data do
-  # @data = @data.page(@_page).per(@_rows) if @_page || @_rows
-  # json.array! @data do |datum|
-  json.array! @data.page(@_page).per(@_rows) do |datum|
-    json.(datum, *datum.show_attrs) if datum.present?
-  end
-end
+          <<~FILE
+            # *** Generated by ZRO ***
+            json.partial! 'api/base', total: @data.size
+            
+            json.data do
+              # @data = @data.page(@_page).per(@_rows) if @_page || @_rows
+              # json.array! @data do |datum|
+              json.array! @data.page(@_page).per(@_rows) do |datum|
+                json.(datum, *datum.show_attrs) if datum.present?
+              end
+            end
           FILE
           ),
 
           show: (
-          <<-FILE
-json.partial! 'api/base', total: 1
-
-json.data do
-  json.array! [ @data ] do |datum|
-    json.(datum, *datum.show_attrs) if datum.present?
-  end
-end
+          <<~FILE
+            # *** Generated by ZRO ***
+            json.partial! 'api/base', total: 1
+            
+            json.data do
+              json.array! [ @data ] do |datum|
+                json.(datum, *datum.show_attrs) if datum.present?
+              end
+            end
           FILE
           ),
 
           success: (
-          <<-FILE
-json.partial! 'api/success'
+          <<~FILE
+            # *** Generated by ZRO ***
+            json.partial! 'api/success'
           FILE
           ),
 
           success_or_not: (
-          <<-FILE
-unless @status
-  # @_code, @_msg = @error_info.present? ? @error_info : ApiError.action_failed.info
-end
-
-json.partial! 'api/base', total: 0
-json.data ''
+          <<~FILE
+            # *** Generated by ZRO ***
+            unless @status
+              # @_code, @_msg = @error_info.present? ? @error_info : ApiError.action_failed.info
+            end
+            
+            json.partial! 'api/base', total: 0
+            json.data ''
           FILE
           ),
       }

data/lib/open_api/config_dsl.rb

@@ -0,0 +1,13 @@
+module OpenApi
+  module ConfigDSL
+    def self.included(base)
+      base.class_eval do
+        module_function
+
+        def info
+          1
+        end
+      end
+    end
+  end
+end

data/lib/open_api/dsl.rb

@@ -1,4 +1,5 @@
-require 'open_api/dsl_inside_block'
+require 'open_api/dsl/api_info_obj'
+require 'open_api/dsl/ctrl_info_obj'
 
 module OpenApi
   module DSL
@@ -13,46 +14,45 @@ module OpenApi
         @_apis_tag  = path.split('/').last.camelize
       end
 
-      def apis_set desc = '', external_doc_url = '', &block
-        @_ctrl_infos = { }
+      def apis_tag name: nil, desc: '', external_doc_url: ''
         # current `tag`, this means that tags is currently divided by controllers.
-        tag = @_ctrl_infos[:tag] = { name: @_apis_tag ||= controller_name.camelize }
+        @_apis_tag = name if name.present?
+        @_apis_tag ||= controller_name.camelize
+        tag = (@_ctrl_infos = { })[:tag] = { name: @_apis_tag }
         tag[:description]  = desc if desc.present?
         tag[:externalDocs] = { description: 'ref', url: external_doc_url } if external_doc_url.present?
+      end
 
+      def components &block
+        apis_tag if @_ctrl_infos.nil?
         current_ctrl = @_ctrl_infos[:components] = CtrlInfoObj.new
-        current_ctrl.instance_eval &block if block_given?
+        current_ctrl.instance_eval &block
+        current_ctrl._process_objs
       end
 
-      def open_api method, summary = '', options = { }, &block
-        apis_set if @_ctrl_infos.nil?
+      def open_api method, summary = '', builder: nil, skip: [ ], use: [ ], &block
+        apis_tag if @_ctrl_infos.nil?
 
         # select the routing info (corresponding to the current method) from the routing list.
         action_path = "#{@_ctrl_path ||= controller_path}##{method}"
         routes_info = ctrl_routes_list&.select { |api| api[:action_path].match? /^#{action_path}$/ }&.first
         pp "[ZRO Warnning] Routing mapping failed: #{@_ctrl_path}##{method}" and return if routes_info.nil?
+        Generator.generate_builder_file(action_path, builder) if builder.present?
 
         # structural { #path: { #http_method:{ } } }, for pushing into Paths Object.
         path = (@_api_infos ||= { })[routes_info[:path]] ||= { }
         current_api = path[routes_info[:http_verb]] =
-            ApiInfoObj.new(action_path, options.slice(:skip, :use))
+            ApiInfoObj.new(action_path, skip: skip, use: use)
                 .merge! description: '', summary: summary, operationId: method, tags: [@_apis_tag],
-                        parameters: [ ], requestBody: '', responses: { }, security: [ ], servers: [ ]
-
-        if (builder = options.values_at(:builder, :bd, :jbuilder).compact.first).present?
-          Generator
-              .generate_builder_file path:    action_path.split('#').first,
-                                     action:  action_path.split('#').last,
-                                     builder: builder
-        end
+                        parameters: [ ], requestBody: '',  responses: { },      security: [ ], servers: [ ]
 
         current_api.tap do |api|
           [method, :all].each do |key| # blocks_store_key
             @_apis_blocks&.[](key)&.each { |blk| api.instance_eval &blk }
           end
-          api.param_use = nil
+          api.param_use = [ ] # skip 和 use 是对 dry 块而言的
           api.instance_eval &block if block_given?
-          api.instance_eval { process_params }
+          api._process_objs
           api.delete_if { |_, v| v.blank? }
         end
       end

data/lib/open_api/dsl/api_info_obj.rb

@@ -0,0 +1,124 @@
+require 'open_api/dsl/common_dsl'
+
+module OpenApi
+  module DSL
+    class ApiInfoObj < Hash
+      include DSL::CommonDSL
+      include DSL::Helpers
+
+      attr_accessor :action_path, :param_skip, :param_use, :param_descs
+
+      def initialize(action_path, skip: [ ], use: [ ])
+        self.action_path = action_path
+        self.param_skip  = skip
+        self.param_use   = use
+        self.param_descs = { }
+      end
+
+      def this_api_is_invalid! explain = ''
+        self[:deprecated] = true
+      end
+
+      alias this_api_is_expired!     this_api_is_invalid!
+      alias this_api_is_unused!      this_api_is_invalid!
+      alias this_api_is_under_repair this_api_is_invalid!
+
+      def desc desc, param_descs = { }
+        self.param_descs = param_descs
+        self[:description] = desc
+      end
+
+      def param param_type, name, type, required, schema_hash = { }
+        return if param_skip.include?(name)
+        return if param_use.present? && !param_use.include?(name)
+
+        _t = nil
+        schema_hash[:desc]  = _t if (_t = param_descs[name]).present?
+        schema_hash[:desc!] = _t if (_t = param_descs["#{name}!".to_sym]).present?
+
+        param_obj = ParamObj.new(name, param_type, type, required, schema_hash)
+        # The definition of the same name parameter will be overwritten
+        index = self[:parameters].map { |p| p.processed[:name] if p.is_a? ParamObj }.index name
+        index.present? ? self[:parameters][index] = param_obj : self[:parameters] << param_obj
+      end
+
+      # Support this writing: (just like `form '', data: { }`)
+      #   do_query by: {
+      #     :search_type => { type: String  },
+      #         :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|
+            args = [ key.dup.to_s.delete('!'), value.delete(:type), value ]
+            key.to_s['!'] ? send("#{param_type}!", *args) : send(param_type, *args)
+          end
+        end unless param_type.to_s['!']
+      end
+
+      def _param_agent name, type, schema_hash = { }
+        param "#{@param_type}".delete('!'), name, type, (@param_type['!'] ? :req : :opt), schema_hash
+      end
+
+      def param_ref component_key, *keys
+        self[:parameters].concat([component_key].concat(keys).map { |key| RefObj.new(:parameter, key).process })
+      end
+
+      def request_body required, media_type, desc = '', schema_hash = { }
+        self[:requestBody] = RequestBodyObj.new(required, media_type, desc, schema_hash).process
+      end
+
+      def _request_body_agent media_type, desc = '', schema_hash = { }
+        request_body (@method_name['!'] ? :req : :opt), media_type, desc, schema_hash
+      end
+
+      def body_ref component_key
+        self[:requestBody] = RefObj.new(:requestBody, component_key).process
+      end
+
+      def override_response code, type_hash
+        _response = self[:responses].fetch(code)
+        self[:responses][code] = _response.override(type_hash).process
+      end
+
+      def response_ref code_compkey_hash
+        code_compkey_hash.each do |code, component_key|
+          self[:responses][code] = RefObj.new(:response, component_key).process
+        end
+      end
+
+      # TODO: 目前只能写一句 request body，包括 form 和 file， 需要同时支持一下扁平化
+      def form desc = '', schema_hash = { }
+        body :form, desc, schema_hash
+      end
+      def form! desc = '', schema_hash = { }
+        body! :form, desc, schema_hash
+      end
+      def file media_type, desc = '', schema_hash = { type: File }
+        body media_type, desc, schema_hash
+      end
+      def file! media_type, desc = '', schema_hash = { type: File }
+        body! media_type, desc, schema_hash
+      end
+
+      def security scheme_name, requirements = [ ]
+        self[:security] << { scheme_name => requirements }
+      end
+
+      def server url, desc
+        self[:servers] << { url: url, description: desc }
+      end
+
+
+      def _process_objs
+        self[:parameters]&.each_with_index do |p, index|
+          self[:parameters][index] = p.process if p.is_a?(ParamObj)
+        end
+
+        self[:responses]&.each do |code, obj|
+          self[:responses][code] = obj.process if obj.is_a?(ResponseObj)
+        end
+      end
+    end # ----------------------------------------- end of ApiInfoObj
+  end
+end

data/lib/open_api/dsl/common_dsl.rb

@@ -0,0 +1,45 @@
+require 'oas_objs/schema_obj'
+require 'oas_objs/param_obj'
+require 'oas_objs/response_obj'
+require 'oas_objs/request_body_obj'
+require 'oas_objs/ref_obj'
+require 'open_api/dsl/helpers'
+
+module OpenApi
+  module DSL
+    module CommonDSL
+      %i[ header header! path path! query query! cookie cookie! ].each do |param_type|
+        define_method param_type do |*args|
+          @param_type = param_type
+          _param_agent *args
+        end
+      end
+
+      %i[ body body! ].each do |method|
+        define_method method do |*args|
+          @method_name = method
+          _request_body_agent *args
+        end
+      end
+
+      # `code`: when defining components, `code` means `component_key`
+      def response code, desc, media_type = nil, schema_hash = { }
+        (self[:responses] ||= { })[code] = ResponseObj.new(desc, media_type, schema_hash)
+      end
+
+      def default_response desc, media_type = nil, schema_hash = { }
+        response :default, desc, media_type, schema_hash
+      end
+
+      { # alias_methods mapping
+          response:         %i[ error_response  resp                      ],
+          default_response: %i[ dft_resp        dft_response              ],
+          error_response:   %i[ other_response  oth_resp  error  err_resp ],
+      }.each do |original_name, aliases|
+        aliases.each do |alias_name|
+          alias_method alias_name, original_name
+        end
+      end
+    end
+  end
+end

data/lib/open_api/dsl/ctrl_info_obj.rb

@@ -0,0 +1,47 @@
+require 'open_api/dsl/common_dsl'
+
+module OpenApi
+  module DSL
+    class CtrlInfoObj < Hash
+      include DSL::CommonDSL
+      include DSL::Helpers
+
+      def schema component_key, type, schema_hash = { }
+        (self[:schemas] ||= { })[component_key] = SchemaObj.new(type, schema_hash).process
+      end
+      arrow_enable :schema
+
+      def param component_key, param_type, name, type, required, schema_hash = { }
+        (self[:parameters] ||= { })[component_key] =
+            ParamObj.new(name, param_type, type, required, schema_hash).process
+      end
+
+      def _param_agent component_key, name, type, schema_hash = { }
+        param component_key,
+              "#{@param_type}".delete('!'), name, type, (@param_type['!'] ? :req : :opt), schema_hash
+      end
+      arrow_enable :_param_agent
+
+      def request_body component_key, required, media_type, desc = '', schema_hash = { }
+        (self[:requestBodies] ||= { })[component_key] =
+            RequestBodyObj.new(required, media_type, desc, schema_hash).process
+      end
+
+      def _request_body_agent component_key, media_type, desc = '', schema_hash = { }
+        request_body component_key,
+                     (@method_name['!'] ? :req : :opt), media_type, desc, schema_hash
+      end
+      arrow_enable :_request_body_agent
+
+      arrow_enable :resp # alias_method 竟然也会指向旧的方法？
+      arrow_enable :response
+
+
+      def _process_objs
+        self[:responses]&.each do |code, obj|
+          self[:responses][code] = obj.process if obj.is_a?(ResponseObj)
+        end
+      end
+    end
+  end
+end

data/lib/open_api/{helpers.rb → dsl/helpers.rb}

@@ -1,6 +1,10 @@
 module OpenApi
   module DSL
     module Helpers
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
       def load_schema(model)
         # About `show_attrs`, see:
         #   (1) BuilderSupport module: https://github.com/zhandao/zero-rails/blob/master/app/models/concerns/builder_support.rb
@@ -19,7 +23,7 @@ module OpenApi
               # TODO: 如何获知关系是 many？因为不能只判断结尾是否 ‘s’
               assoc_model = Object.const_get(attr.to_s.split('_').first.singularize.camelize)
               { attr => load_schema(assoc_model) }
-            end
+            end rescue next
           end
         else
           model&.columns&.map do |column|
@@ -30,6 +34,28 @@ module OpenApi
           end
         end&.compact&.reduce({ }, :merge)
       end
+
+      # Arrow Writing:
+      #   response :RespComponent => [ '200', 'success', :json ]
+      # It is equivalent to:
+      #   response :RespComponent, '200', 'success', :json
+      # But I think, in the definition of a component,
+      #   the key-value (arrow) writing is easy to understand.
+      def arrow_writing_support
+        proc do |args, executor|
+          _args = args.size == 1 && args.first.is_a?(Hash) ? args[0].to_a.flatten : args
+          send executor, *_args
+        end
+      end
+
+      module ClassMethods
+        def arrow_enable method
+          alias_method "_#{method}".to_sym, method
+          define_method method do |*args|
+            arrow_writing_support.call(args, "_#{method}")
+          end
+        end
+      end
     end
   end
 end

data/lib/open_api/generator.rb

@@ -40,7 +40,7 @@ module OpenApi
             ActiveSupport::HashWithIndifferentAccess.new(doc.delete_if { |_, v| v.blank? })
       end
 
-      def write_docs(generate_files = true)
+      def write_docs(generate_files: true)
         docs = generate_docs
         return unless generate_files
         output_path = Config.file_output_path
@@ -48,23 +48,26 @@ module OpenApi
         max_length = docs.keys.map(&:size).sort.last
         puts '[ZRO] * * * * * *'
         docs.each do |doc_name, doc|
-          puts "[ZRO] `%#{max_length}s.json` is generated." % "#{doc_name}"
+          puts "[ZRO] `%#{max_length}s.json` has been generated." % "#{doc_name}"
           File.open("#{output_path}/#{doc_name}.json", 'w') { |file| file.write JSON.pretty_generate doc }
         end
         # pp $open_apis
       end
     end
 
-    def self.generate_builder_file(option)
+    def self.generate_builder_file(action_path, builder)
       return unless Config.generate_jbuilder_file
-      return unless option[:builder]
-      dir_path = "app/views/#{option[:path]}"
+      return if builder.nil?
+
+      path, action = action_path.split('#')
+      dir_path = "app/views/#{path}"
       FileUtils.mkdir_p dir_path
-      file_path = "#{dir_path}/#{option[:action]}.json.jbuilder"
-      File.open(file_path, 'w') do |file|
-        file.write Config.jbuilder_templates[option[:builder]]
-        puts "[ZRO] JBuilder file generated: #{option[:path]}/#{option[:action]}"
-      end unless !Config.overwrite_jbuilder_file && File::exists?(file_path)
+      file_path = "#{dir_path}/#{action}.json.jbuilder"
+
+      unless !Config.overwrite_jbuilder_file && File::exists?(file_path)
+        File.open(file_path, 'w') { |file| file.write Config.jbuilder_templates[builder] }
+        puts "[ZRO] JBuilder file has been generated: #{path}/#{action}"
+      end
     end
 
     def self.generate_routes_list
@@ -79,7 +82,7 @@ module OpenApi
         {
             http_verb: infos[0].downcase, # => "get"
             path: infos[1][0..-11].split('/').map do |item|
-                    item.match?(/:/) ? "{#{item[1..-1]}}" : item
+                    item[':'] ? "{#{item[1..-1]}}" : item
                   end.join('/'),          # => "/api/v1/examples/{id}"
             action_path: infos[2]         # => "api/v1/examples#index"
         } rescue next

data/lib/open_api/version.rb

@@ -1,3 +1,3 @@
 module OpenApi
-  VERSION = '1.3.0'
+  VERSION = '1.3.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zero-rails_openapi
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.3.1
 platform: ruby
 authors:
 - zhandao
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-10-26 00:00:00.000000000 Z
+date: 2017-11-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -90,10 +90,13 @@ files:
 - lib/oas_objs/schema_obj.rb
 - lib/open_api.rb
 - lib/open_api/config.rb
+- lib/open_api/config_dsl.rb
 - lib/open_api/dsl.rb
-- lib/open_api/dsl_inside_block.rb
+- lib/open_api/dsl/api_info_obj.rb
+- lib/open_api/dsl/common_dsl.rb
+- lib/open_api/dsl/ctrl_info_obj.rb
+- lib/open_api/dsl/helpers.rb
 - lib/open_api/generator.rb
-- lib/open_api/helpers.rb
 - lib/open_api/version.rb
 - zero-rails_openapi.gemspec
 homepage: https://github.com/zhandao/zero-rails_openapi
@@ -116,7 +119,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.12
+rubygems_version: 2.6.13
 signing_key: 
 specification_version: 4
 summary: Generate the OpenAPI Specification 3 documentation for Rails application.

data/lib/open_api/dsl_inside_block.rb

@@ -1,214 +0,0 @@
-require 'oas_objs/schema_obj'
-require 'oas_objs/param_obj'
-require 'oas_objs/response_obj'
-require 'oas_objs/request_body_obj'
-require 'oas_objs/ref_obj'
-require 'open_api/helpers'
-
-module OpenApi
-  module DSL
-    module CommonDSL
-      def arrow_writing_support
-        proc do |args, executor|
-          if args.count == 1 && args.first.is_a?(Hash)
-            send(executor, args[0].keys.first, *args[0].values.first)
-          else
-            send(executor, *args)
-          end
-        end
-      end
-
-      %i[header header! path path! query query! cookie cookie!].each do |param_type|
-        define_method param_type do |*args|
-          @param_type = param_type
-          _param_agent *args
-        end
-      end
-
-      %i[body body!].each do |method|
-        define_method method do |*args|
-          @method_name = method
-          _request_body_agent *args
-        end
-      end
-
-      # code represents `component_key` when declare response component
-      def _response code, desc, media_type = nil, schema_hash = { }
-        (self[:responses] ||= { }).merge! ResponseObj.new(code, desc, media_type, schema_hash).process
-      end
-
-      def response *args
-        arrow_writing_support.call(args, :_response)
-      end
-
-      def default_response desc, media_type = nil, schema_hash = { }
-        response :default, desc, media_type, schema_hash
-      end
-
-      { # alias_methods mapping
-          response:         %i[ error_response  resp                      ],
-          default_response: %i[ dft_resp        dft_response              ],
-          error_response:   %i[ other_response  oth_resp  error  err_resp ],
-      }.each do |original_name, aliases|
-        aliases.each do |alias_name|
-          alias_method alias_name, original_name
-        end
-      end
-    end # ----------------------------------------- end of CommonDSL
-
-
-
-
-    class CtrlInfoObj < Hash
-      include DSL::CommonDSL
-
-      def _schema component_key, type, schema_hash = { }
-        (self[:schemas] ||= { }).merge! component_key => SchemaObj.new(type, schema_hash).process
-      end
-      def schema *args
-        arrow_writing_support.call(args, :_schema)
-      end
-
-      def param component_key, param_type, name, type, required, schema_hash = { }
-        (self[:parameters] ||= { })
-            .merge! component_key => ParamObj.new(name, param_type, type, required, schema_hash).process
-      end
-
-      def _param_agent *args
-        arrow_writing_support.call(args, :_param_arg_agent)
-      end
-
-      def _param_arg_agent component_key, name, type, schema_hash = { }
-        param component_key, "#{@param_type}".delete('!'), name, type,
-              ("#{@param_type}".match?(/!/) ? :req : :opt), schema_hash
-      end
-
-      def request_body component_key, required, media_type, desc = '', schema_hash = { }
-        self[:requestBodies] = { component_key => RequestBodyObj.new(required, media_type, desc, schema_hash).process }
-      end
-
-      def _request_body_agent *args
-        arrow_writing_support.call(args, :_request_body_arg_agent)
-      end
-
-      def _request_body_arg_agent component_key, media_type, desc = '', schema_hash = { }
-        request_body component_key, ("#{@method_name}".match?(/!/) ? :req : :opt), media_type, desc, schema_hash
-      end
-    end # ----------------------------------------- end of CtrlInfoObj
-
-
-
-
-    class ApiInfoObj < Hash
-      include DSL::CommonDSL
-      include DSL::Helpers
-
-      attr_accessor :action_path, :param_skip, :param_use
-      def initialize(action_path, options = { })
-        self.action_path = action_path
-        self.param_skip  = options[:skip] || [ ]
-        self.param_use   = options[:use]  || [ ]
-      end
-
-      def this_api_is_invalid! explain = ''
-        self[:deprecated] = true
-      end
-      alias_method :this_api_is_expired!,     :this_api_is_invalid!
-      alias_method :this_api_is_unused!,      :this_api_is_invalid!
-      alias_method :this_api_is_under_repair, :this_api_is_invalid!
-
-      def desc desc, inputs_descs = { }
-        @inputs_descs = inputs_descs
-        merge_desc_for_dryed_param
-        self[:description] = desc
-      end
-
-      # TODO: HACK
-      def merge_desc_for_dryed_param
-        @inputs_descs.each do |param_name, desc|
-          self[:parameters].each do |param|
-            if param_name.match?(?!) && param.processed[:name].to_s == param_name.to_s.delete(?!)
-              param.merge!(desc!: desc).process
-            end
-          end
-        end
-      end
-
-      def param param_type, name, type, required, schema_hash = { }
-        return if param_skip.include? name
-        return unless param_use.include? name if param_use.present?
-
-        if @inputs_descs&.[](name).present?
-          schema_hash[:desc] = @inputs_descs[name]
-        elsif @inputs_descs&.[]("#{name}!".to_sym).present?
-          schema_hash[:desc!] = @inputs_descs["#{name}!".to_sym]
-        end
-
-        param_obj = ParamObj.new(name, param_type, type, required, schema_hash)
-        # The definition of the same name parameter will be overwritten
-        index = self[:parameters].map do |p|
-          p.processed[:name] if p.is_a? ParamObj
-        end.index name
-        if index.present?
-          self[:parameters][index] = param_obj
-        else
-          self[:parameters] << param_obj
-        end
-      end
-
-      def process_params
-        self[:parameters].each_with_index do |p, index|
-          self[:parameters][index] = p.is_a?(ParamObj) ? p.process : p
-        end
-      end
-
-      def _param_agent name, type, schema_hash = { }
-        param "#{@param_type}".delete('!'), name, type, ("#{@param_type}".match?(/!/) ? :req : :opt), schema_hash
-      end
-
-      def param_ref component_key, *keys
-        self[:parameters].concat [component_key].concat(keys).map { |key| RefObj.new(:parameter, key).process }
-      end
-
-      def request_body required, media_type, desc = '', schema_hash = { }
-        self[:requestBody] = RequestBodyObj.new(required, media_type, desc, schema_hash).process
-      end
-
-      def _request_body_agent media_type, desc = '', schema_hash = { }
-        request_body ("#{@method_name}".match?(/!/) ? :req : :opt), media_type, desc, schema_hash
-      end
-
-      def body_ref component_key
-        self[:requestBody] = RefObj.new(:requestBody, component_key).process
-      end
-
-      def response_ref code_compkey_hash
-        code_compkey_hash.each do |code, component_key|
-          self[:responses].merge! code => RefObj.new(:response, component_key).process
-        end
-      end
-
-      # TODO: 目前只能写一句 request body，包括 form 和 file， 需要同时支持一下扁平化
-      def form desc = '', schema_hash = { }
-        body :form, desc, schema_hash
-      end
-      def form! desc = '', schema_hash = { }
-        body! :form, desc, schema_hash
-      end
-      def file media_type, desc = '', schema_hash = { type: File }
-        body media_type, desc, schema_hash
-      end
-      def file! media_type, desc = '', schema_hash = { type: File }
-        body! media_type, desc, schema_hash
-      end
-
-      def security scheme_name, requirements = [ ]
-        self[:security] << { scheme_name => requirements }
-      end
-
-      def server url, desc
-        self[:servers] << { url: url, description: desc }
-      end
-    end # ----------------------------------------- end of ApiInfoObj
-  end
-end