zero-rails_openapi 1.4.3 → 1.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fefcfd0fc562daad7532e1dadd0121e8c30c0adb
-  data.tar.gz: 25cf51020674fce5fb428f6b121b6c6a25c02c72
+  metadata.gz: 8973e94b7dd3112572e08cbf838ed9d5288ae092
+  data.tar.gz: a89c1d354004e40c6441c0ede06b848111a5c8bb
 SHA512:
-  metadata.gz: 77306d030cba3bfbcb7f6d31eaac31c9ed7dd60355a012166a040633cd6420ebe898b483dcef1fae571da47fcb64871489da7c91069014246dd788e78c2e0815
-  data.tar.gz: 5ad12c05afbf059b177bc1e797e401f49595d7be696e386f89b6e1f945daa511ebc2919c2564b4439e07c0951147682c3ee116efc0f9de4708f845e8e06327b8
+  metadata.gz: 170477a27cca4298664b2d95a7ac65879b79bcbd64ab42f23aaa917b0c45f61506e54c7d5027d9503ae96a04a031f0de34c1dc21cf0ad96ffd5962d98ec9916f
+  data.tar.gz: 532e6c8c37abdcd5e7d00c5f10cdedc5ceab6c2e187760a636c1dfda9b4d5b71b9aa5b6ac5d85cfca69c7b8fd3aa21de3a2ff0c2170e790104993a1317320b17

data/.gitignore

@@ -9,5 +9,6 @@
 
 # rspec failure tracking
 .rspec_status
+coverage
 
 .idea/*

data/.travis.yml

@@ -1,5 +1,16 @@
 sudo: false
 language: ruby
 rvm:
-  - 2.4.1
+  - 2.4.0
 before_install: gem install bundler -v 1.16.0.pre.2
+env:
+  global:
+    - CC_TEST_REPORTER_ID=fd0a238819079b92c19e99f5f4d6dcc8a5b5b2baf087fceb3723837604b5b0e9
+before_script:
+  - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
+  - chmod +x ./cc-test-reporter
+  - ./cc-test-reporter before-build
+script:
+  - bundle exec rspec
+after_script:
+  - ./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT

data/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Version Changelog
 
+## [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)
+
+### Completed the test code (250+ examples), and make it 100% coverage.
+
+### Feature
+
+1. `type: [String, Integer ..]` will generate an array, which's items
+   would be a oneOf combined schema.
+
+### Fixed:
+
+1. `desc` will override dry's.
+2. `type: something` is passed to `schema_hash`,  but not `type`.
+3. Should not `skip` the params inside block.
+4. `body_ref` invalid.
+5. schema `length`'s order is reversed.
+6. Example Obj ref.
+
+### Added:
+
+1. Use `simplecov`.
+2. CodeClimate test hook.
+3. Test's support.
+4. Designed RSpec matchers `have_keys` and `have_size`.
+5. Designed a set of RSpec's DSL (DSSL) for testing.
+
+### Changed:
+
+1. WILL NOT do `recognize_is_options_in`.
+2. `instance_eval` => `instance_exec` in dsl.rb.
+3. Guard Clause for `generate_docs` and where schema could be defined.
+4. Change signature of `server` in `api`.
+5. Simplify `recursive`s.
+6. `enum: { 'desc' => :enum1 }` => `enum!: { 'desc' => :enum1 }`
+
 ## [1.4.2 & 1.4.3] - 2017/12/11&13 - [view diff](https://github.com/zhandao/zero-rails_openapi/compare/v1.4.1...v1.4.3)
 
 ### Feature

data/Gemfile

@@ -1,4 +1,4 @@
-source "https://rubygems.org"
+source 'https://rubygems.org'
 
 git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    zero-rails_openapi (1.4.3)
+    zero-rails_openapi (1.5.1)
       activesupport (>= 3)
       rails (>= 3)
 
@@ -50,20 +50,20 @@ GEM
     concurrent-ruby (1.0.5)
     crass (1.0.3)
     diff-lcs (1.3)
+    docile (1.1.5)
     erubi (1.7.0)
     globalid (0.4.1)
       activesupport (>= 4.2.0)
     i18n (0.9.1)
       concurrent-ruby (~> 1.0)
+    json (2.1.0)
     loofah (2.1.1)
       crass (~> 1.0.2)
       nokogiri (>= 1.5.9)
-    mail (2.6.6)
-      mime-types (>= 1.16, < 4)
+    mail (2.7.0)
+      mini_mime (>= 0.1.1)
     method_source (0.9.0)
-    mime-types (3.1)
-      mime-types-data (~> 3.2015)
-    mime-types-data (3.2016.0521)
+    mini_mime (1.0.0)
     mini_portile2 (2.3.0)
     minitest (5.10.3)
     nio4r (2.1.0)
@@ -109,6 +109,11 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.6.0)
     rspec-support (3.6.0)
+    simplecov (0.15.1)
+      docile (~> 1.1.0)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.2)
     sprockets (3.7.1)
       concurrent-ruby (~> 1.0)
       rack (> 1, < 3)
@@ -122,7 +127,7 @@ GEM
       thread_safe (~> 0.1)
     websocket-driver (0.6.5)
       websocket-extensions (>= 0.1.0)
-    websocket-extensions (0.1.2)
+    websocket-extensions (0.1.3)
 
 PLATFORMS
   ruby
@@ -131,6 +136,7 @@ DEPENDENCIES
   bundler (~> 1.16.a)
   rake (~> 10.0)
   rspec (~> 3.0)
+  simplecov
   zero-rails_openapi!
 
 BUNDLED WITH

data/README.md

@@ -3,6 +3,7 @@
   [![Gem Version](https://badge.fury.io/rb/zero-rails_openapi.svg)](https://badge.fury.io/rb/zero-rails_openapi)
   [![Build Status](https://travis-ci.org/zhandao/zero-rails_openapi.svg?branch=master)](https://travis-ci.org/zhandao/zero-rails_openapi)
   [![Maintainability](https://api.codeclimate.com/v1/badges/471fd60f6eb7b019ceed/maintainability)](https://codeclimate.com/github/zhandao/zero-rails_openapi/maintainability)
+  [![Test Coverage](https://api.codeclimate.com/v1/badges/471fd60f6eb7b019ceed/test_coverage)](https://codeclimate.com/github/zhandao/zero-rails_openapi/test_coverage)
   [![Gitter Chat](https://badges.gitter.im/zero-rails_openapi/Lobby.svg)](https://gitter.im/zero-rails_openapi/Lobby)
   
   Concise DSL for generating OpenAPI Specification 3 (**OAS3**, formerly Swagger3) JSON documentation for Rails application, 
@@ -13,6 +14,9 @@
   **Hi, here is ZhanDao = ▽ =  
   I think it's a very useful tool when you want to write API document clearly.  
   I'm looking forward to your issue and PR, thanks!**
+  
+  And, if you have any questions, please read the test code first.  
+  such as [api DSL](spec/api_info_obj_spec.rb) and [schema Obj](spec/oas_objs/schema_obj_spec.rb).
 
 ## Table of Contents
 
@@ -271,7 +275,7 @@
        email: 'desc of the parameter :email'
   ```
 
-  You can of course describe the input in it's DSL method (like `query! :done ...`, [this line](https://github.com/zhandao/zero-rails_openapi#-dsl-usage-example)), 
+  You can of course describe the input in it's DSL method (like `query! :done ...`, [this line](https://github.com/zhandao/zero-rails_openapi#dsl-usage-example)), 
   but that will make it long and ugly. We recommend that unite descriptions in this place.
   
   In addition, when you want to dry the same parameters (each with a different description), it will be of great use.
@@ -445,8 +449,8 @@
   4. *[IMPORTANT]* Each request bodies you declared will **FUSION** together. <a name="fusion"></a>  
      (1) Media-Types will be merged to `requestBody["content"]`
      ```ruby
-     form 'desc', data: { }
-     body :json, 'desc', data: { }
+     form data: { }, desc: 'desc'
+     body :json, data: { }, desc: 'desc'
      # will generate: "content": { "multipart/form-data": { }, "application/json": { } }
      ```
      (2) The same media-types will fusion, but not merge:  
@@ -476,6 +480,7 @@
   # method signature
   response(code, desc, media_type = nil, data: { }, type: nil)
   # usage
+  resp 200, 'json response', :json, data: { name: 'test' }
   response 200, 'query result', :pdf, type: File
   # same as:
   response 200, 'query result', :pdf, data: File
@@ -550,9 +555,9 @@
   
   ```ruby
   # method signature
-  server(url, desc)
+  server(url, desc: '')
   # usage
-  server 'http://localhost:3000', 'local'
+  server 'http://localhost:3000', desc: 'local'
   ```
   
 ### DSL methods inside [components]()'s block ([code source](lib/open_api/dsl/components.rb))
@@ -687,7 +692,7 @@
   
   You can also use Hash to define `enum`:
   ```ruby
-  query :view, String, desc: 'allows values<br/>', enum: {
+  query :view, String, desc: 'allows values<br/>', enum!: {
           'all goods (default)': :all,
                   'only online': :online,
                  'only offline': :offline,
@@ -715,7 +720,7 @@
 ### Trick6 - Combined Schema (one_of / all_of / any_of / not)
 
   ```ruby
-  query :combination, one_of: [ :GoodSchema, String, { type: Integer, desc: 'integer input'}]
+  query :combination, one_of: [ :GoodSchema, String, { type: Integer, desc: 'integer input' } ]
   
   form '', data: {
       :combination_in_form => { any_of: [ Integer, String ] }

data/README_zh.md

@@ -3,6 +3,7 @@
   [![Gem Version](https://badge.fury.io/rb/zero-rails_openapi.svg)](https://badge.fury.io/rb/zero-rails_openapi)
   [![Build Status](https://travis-ci.org/zhandao/zero-rails_openapi.svg?branch=master)](https://travis-ci.org/zhandao/zero-rails_openapi)
   [![Maintainability](https://api.codeclimate.com/v1/badges/471fd60f6eb7b019ceed/maintainability)](https://codeclimate.com/github/zhandao/zero-rails_openapi/maintainability)
+  [![Test Coverage](https://api.codeclimate.com/v1/badges/471fd60f6eb7b019ceed/test_coverage)](https://codeclimate.com/github/zhandao/zero-rails_openapi/test_coverage)
   [![Gitter Chat](https://badges.gitter.im/zero-rails_openapi/Lobby.svg)](https://gitter.im/zero-rails_openapi/Lobby)
   
   一套简洁的 DSL，用于为 Rails 应用生成 OpenAPI Specification 3 (**OAS3**, 旧称「Swagger3」) 标准的 JSON 文档。  
@@ -15,6 +16,10 @@
   你还可以复用其所[产出](#about-openapidocs-and-openapipaths_index)来写一些扩展，比如参数自动校验什么的（我有写哦）。  
   有什么想法敬请 PR，谢过！
   另外，走过路过不妨来个 star？**
+  
+  另外，如果对其行为表现有任何疑惑，敬请先阅读测试代码，这其中已然表明清楚我的大多数考量。  
+  值得一读的测试：[api DSL](spec/api_info_obj_spec.rb) 以及 [schema Obj](spec/oas_objs/schema_obj_spec.rb)。
+
 
 ## Table of Contents
 

data/documentation/examples/auto_gen_desc.rb

@@ -12,7 +12,7 @@ class V1::GoodsDoc < BaseDoc
 
     # Instead of:
     # query :view,        String, enum: %w[ all online offline expensive cheap ]
-    query :view, String, enum: {
+    query :view, String, enum!: {
         'all goods (default)': :all,
                 'only online': :online,
                'only offline': :offline,

data/documentation/examples/goods_doc.rb

@@ -1,4 +1,4 @@
-class V2::GoodsDoc < BaseDoc
+class V2::GoodsDoc < ApiDoc
   SCHEMA_DRY = { a: 1, b: 2 }
 
   #                                 skip: [ 'Token' ] do # you can also skip parameters
@@ -8,7 +8,7 @@ class V2::GoodsDoc < BaseDoc
          search_type!: 'search field, allows:<br/>'
 
     # Single `query`
-    query :view, String, enum: {
+    query :view, String, enum!: {
         'all goods (default)': :all,
                 'only online': :online,
                'only offline': :offline,

data/lib/oas_objs/combined_schema.rb

@@ -13,16 +13,14 @@ module OpenApi
         @schemas = combined_schema.values.first
       end
 
-      def process_for(param_name = nil, options = { desc_inside: false })
+      def process(options = { inside_desc: false })
         processed[@mode] = @schemas.map do |schema|
           type = schema.is_a?(Hash) ? schema[:type] : schema
           schema = { } unless schema.is_a?(Hash)
-          SchemaObj.new(type, schema).process_for(param_name, options)
+          SchemaObj.new(type, schema).process(options)
         end
         processed
       end
-
-      alias process process_for
     end
   end
 end

data/lib/oas_objs/example_obj.rb

@@ -21,7 +21,7 @@ module OpenApi
               if keys_of_value.present? && value.is_a?(Array)
                 { value: Hash[keys_of_value.zip(value)] }
               elsif value.is_a?(Symbol) && value['$']
-                { '$ref': RefObj.new(:example, value).process }
+                RefObj.new(value.to_s.delete('$'), :example).process
               else
                 { value: value }
               end

data/lib/oas_objs/helpers.rb

@@ -38,20 +38,10 @@ module OpenApi
 
     def to_processed(who)
       return processed unless truly_present?(@assign)
-
-      if who.is_a?(Symbol)
-        send("#{who}=", @assign)
-      else
-        processed[who.to_sym] = @assign
-      end
-
+      processed[who.to_sym] = @assign
       processed
     end
 
-    def to(who)
-      self[who.to_sym] = @assign if truly_present?(@assign)
-    end
-
     def then_merge! # to_processed
       processed.tap { |it| it.merge! @assign if truly_present?(@assign) }
     end

data/lib/oas_objs/media_type_obj.rb

@@ -29,6 +29,7 @@ module OpenApi
       # https://en.wikipedia.org/wiki/Media_type
       # https://zh.wikipedia.org/wiki/%E4%BA%92%E8%81%94%E7%BD%91%E5%AA%92%E4%BD%93%E7%B1%BB%E5%9E%8B
       # https://www.iana.org/assignments/media-types/media-types.xhtml
+      # :nocov:
       def media_type_mapping(media_type)
         return media_type if media_type.is_a? String
         case media_type
@@ -60,6 +61,7 @@ module OpenApi
         else             nil
         end
       end
+      # :nocov:
     end
   end
 end

data/lib/oas_objs/param_obj.rb

@@ -20,12 +20,12 @@ module OpenApi
 
       def process
         assign(desc).to_processed 'description'
-        processed.tap { |it| it[:schema] = schema.process_for(processed[:name]) }
+        processed.tap { |it| it[:schema] = schema.process }
       end
 
       def desc
         return _desc unless __desc.present?
-        schema.preprocess_with_desc __desc, self[:name]
+        schema.preprocess_with_desc __desc
       end
 
 

data/lib/oas_objs/response_obj.rb

@@ -22,12 +22,6 @@ module OpenApi
         assign(media_types.map(&:process).reduce({ }, &fusion)).to_processed 'content'
         processed
       end
-
-      def override(type_hash)
-        @hash[:type].merge!(type_hash)
-        self.media_type = MediaTypeObj.new(@mt, @hash)
-        self
-      end
     end
   end
 end

data/lib/oas_objs/schema_obj.rb

@@ -26,39 +26,34 @@ module OpenApi
         merge! schema_hash
       end
 
-
-      def process_for(param_name = nil, options = { desc_inside: false })
-        return processed if @preprocessed
+      def process(options = { inside_desc: false })
+        return processed if preprocessed
 
         processed.merge!(processed_type)
         reducx(
             processed_enum_and_length,
             processed_range,
-            processed_is_and_format(param_name),
+            processed_is_and_format,
             {
                 pattern:    _pattern.is_a?(String)? _pattern : _pattern&.inspect&.delete('/'),
-                default:    nil,
+                default:    _default,
                 examples:   self[:examples].present? ? ExampleObj.new(self[:examples], self[:exp_by]).process : nil
             },
-            { as: _as, permit: _permit, not_permit: _npermit, req_if: _req_if, opt_if: _opt_if, blankable: _blank }
+            { as: _as, permit: _permit, not_permit: _npermit, req_if: _req_if, opt_if: _opt_if, blankable: _blank },
         ).then_merge!
-        processed[:default] = _default unless _default.nil?
-
-        reducx(processed_desc(options)).then_merge!
+        reducx(processed_desc(options)).then_merge! # TODO
       end
 
-      alias process process_for
-
-      def preprocess_with_desc desc, param_name = nil
+      def preprocess_with_desc desc
         self.__desc = desc
-        process_for param_name
+        process
         self.preprocessed = true
         __desc
       end
 
       def processed_desc(options)
-        result = __desc ? self.__desc = auto_generate_desc : _desc
-        options[:desc_inside] ? { description: result } : nil
+        result = __desc ? auto_generate_desc : _desc
+        options[:inside_desc] ? { description: result } : nil
       end
 
       def processed_type(type = self.type)
@@ -66,16 +61,16 @@ module OpenApi
         if t.is_a? Hash
           processed_hash_type(t)
         elsif t.is_a? Array
-          recursive_array_type(t)
+          processed_array_type(t)
         elsif t.is_a? Symbol
           RefObj.new(:schema, t).process
-        elsif t.in? %w[float double int32 int64]
-          { type: t.match?('int') ? 'integer' : 'number', format: t}
-        elsif t.in? %w[binary base64]
-          { type: 'string', format: t}
-        elsif t.eql? 'file'
+        elsif t.in? %w[ float double int32 int64 ]
+          { type: t.match?('int') ? 'integer' : 'number', format: t }
+        elsif t.in? %w[ binary base64 ]
+          { type: 'string', format: t }
+        elsif t == 'file'
           { type: 'string', format: Config.dft_file_format }
-        elsif t.eql? 'datetime'
+        elsif t == 'datetime'
           { type: 'string', format: 'date-time' }
         else # other string
           { type: t }
@@ -84,32 +79,38 @@ module OpenApi
 
       def processed_hash_type(t)
         # For supporting this:
-        #   form 'desc', data: {
+        #   form 'desc', type: {
         #     id!: { type: Integer, enum: 0..5, desc: 'user id' }
-        # }
+        # }, should have description within schema
         if t.key?(:type)
-          SchemaObj.new(t[:type], t).process_for(@prop_name, desc_inside: true)
-          # For supporting combined schema in nested schema.
+          SchemaObj.new(t[:type], t).process(inside_desc: true)
+
+        # For supporting combined schema in nested schema.
         elsif (t.keys & %i[ one_of any_of all_of not ]).present?
-          CombinedSchema.new(t).process_for(@prop_name, desc_inside: true)
+          CombinedSchema.new(t).process(inside_desc: true)
         else
-          recursive_obj_type(t)
+          processed_obj_type(t)
         end
       end
 
       def processed_enum_and_length
         process_enum_info
-        process_enum_lth_range
+        process_range_enum_and_lth
 
         # generate length range fields by _lth array
-        lth = _length || [ ]
-        max = lth.is_a?(Array) ? lth.first : ("#{lth}".match?('ge') ? "#{lth}".split('_').last.to_i : nil)
-        min = lth.is_a?(Array) ? lth.last : ("#{lth}".match?('le') ? "#{lth}".split('_').last.to_i : nil)
+        if (lth = _length || [ ]).is_a?(Array)
+          min, max = [lth.first&.to_i, lth.last&.to_i]
+        elsif lth['ge']
+          max = lth.to_s.split('_').last.to_i
+        elsif lth['le']
+          min = lth.to_s.split('_').last.to_i
+        end
+
         if processed[:type] == 'array'
-          { minItems: max, maxItems: min }
+          { minItems: min, maxItems: max }
         else
-          { minLength: max, maxLength: min }
-        end.merge!(enum: _enum).keep_if &value_present
+          { minLength: min, maxLength: max }
+        end.merge(enum: _enum).keep_if &value_present
       end
 
       def processed_range
@@ -122,22 +123,11 @@ module OpenApi
         }.keep_if &value_present
       end
 
-      def processed_is_and_format(name)
-        return if name.nil?
-        recognize_is_options_in name
-        { }.tap do |it|
-          # `format` that generated in process_type() may be overwrote here.
-          it[:format] = _format || _is if processed[:format].blank? || _format.present?
-          it[:is] = _is
-        end
-      end
-
-      def recognize_is_options_in(name)
-        return unless _is.nil?
-        # identify whether `is` patterns matched the name, if so, generate `is`.
-        Config.is_options.each do |pattern|
-          (self._is = pattern) or break if name.match?(/#{pattern}/)
-        end
+      def processed_is_and_format
+        result = { is: _is }
+        # `format` that generated in process_type() may be overwrote here.
+        result[:format] = _format || _is if processed[:format].blank? || _format.present?
+        result
       end
 
 

data/lib/oas_objs/schema_obj_helpers.rb

@@ -3,65 +3,62 @@ module OpenApi
     module SchemaObjHelpers
       # TODO: more info and desc configure
       def auto_generate_desc
-        if processed[:enum].present?
-          if @enum_info.present?
-            @enum_info.each_with_index do |(info, value), index|
-              __desc.concat "<br/>#{index + 1}/ #{info}: #{value}"
-            end
-          else
-            processed[:enum].each_with_index do |value, index|
-              __desc.concat "<br/>#{index + 1}/ #{value}"
-            end
+        return __desc if processed[:enum].blank?
+
+        if @enum_info.present?
+          @enum_info.each_with_index do |(info, value), index|
+            __desc.concat "<br/>#{index + 1}/ #{info}: #{value}"
+          end
+        else
+          processed[:enum].each_with_index do |value, index|
+            __desc.concat "<br/>#{index + 1}/ #{value}"
           end
         end
         __desc
       end
 
-      def recursive_obj_type(t) # ZRO use { prop_name: prop_type } to represent object structure
-        return processed_type(t) if !t.is_a?(Hash) || (t.keys & %i[ type one_of any_of all_of not ]).present?
+      def processed_obj_type(t)
+        obj_type = { type: 'object', properties: { }, required: [ ] }
 
-        _schema = {
-            type: 'object',
-            properties: { },
-            required: [ ]
-        }
         t.each do |prop_name, prop_type|
-          @prop_name = prop_name
-          _schema[:required] << "#{prop_name}".delete('!') if prop_name['!']
-          _schema[:properties]["#{prop_name}".delete('!').to_sym] = recursive_obj_type prop_type
+          obj_type[:required] << prop_name.to_s.delete('!') if prop_name['!']
+          obj_type[:properties][prop_name.to_s.delete('!').to_sym] = processed_type(prop_type)
         end
-        _schema.keep_if(&value_present)
+        obj_type.keep_if &value_present
       end
 
-      def recursive_array_type(t)
-        return processed_type(t) unless t.is_a? Array
-
+      def processed_array_type(t)
+        t = t.size == 1 ? t.first : { one_of: t }
         {
             type: 'array',
-            # TODO: [[String], [Integer]] <= One Of? Object?(0=>[S], 1=>[I])
-            items: recursive_array_type(t.first)
+            items: processed_type(t)
         }
       end
 
-      def process_enum_lth_range
-        self[:_enum] = _enum.to_a if _enum.present? && _enum.is_a?(Range)
-        self[:_length] = _length.to_a if _length.present? && _length.is_a?(Range)
+      def process_range_enum_and_lth
+        self[:_enum] = str_range_2a(_enum) if _enum.present? && _enum.is_a?(Range)
+        self[:_length] = str_range_2a(_length) if _length.present? && _length.is_a?(Range)
 
-        # generate_enums_by_enum_array
         values = _enum || _value
         self._enum = Array(values) if truly_present?(values)
       end
 
+      def str_range_2a(val)
+        val_class = val.first.class
+        action = "to_#{val_class.to_s.downcase[0]}".to_sym
+        (val.first.to_s..val.last.to_s).to_a.map(&action)
+      end
+
       def process_enum_info
         # Support this writing for auto generating desc from enum.
-        #   enum: {
-        #     'all_data': :all,
-        #     'one_page': :one
+        #   enum!: {
+        #     'all_desc': :all,
+        #     'one_desc': :one
         # }
-        if _enum.is_a? Hash
-          @enum_info = _enum
-          self._enum = _enum.values
-        end
+        self._enum ||= self[:enum!]
+        return unless self[:enum!].is_a? Hash
+        @enum_info = self[:enum!]
+        self._enum = self[:enum!].values
       end
     end
   end

data/lib/open_api.rb

@@ -1,7 +1,7 @@
-require "open_api/version"
-require "open_api/config"
-require "open_api/generator"
-require "open_api/dsl"
+require 'open_api/version'
+require 'open_api/config'
+require 'open_api/generator'
+require 'open_api/dsl'
 
 module OpenApi
   include Generator

data/lib/open_api/config.rb

@@ -47,10 +47,6 @@ module OpenApi
       }
     end
 
-    cattr_accessor :is_options do
-      %w[ email phone mobile password uuid uri url time date ]
-    end
-
     cattr_accessor :dft_file_format do
       'binary'
     end

data/lib/open_api/config_dsl.rb

@@ -10,7 +10,7 @@ module OpenApi
         end
 
         def info version:, title:, desc: '', **addition
-          open_api_docs[@api][:info] = { version: version, title: title, description:  desc, **addition }
+          open_api_docs[@api][:info] = { version: version, title: title, description: desc, **addition }
         end
 
         def server url, desc: ''
@@ -30,7 +30,7 @@ module OpenApi
           security_scheme scheme_name, { type: 'http', scheme: 'bearer', bearerFormat: format }.merge(other_info)
         end
 
-        def api_key scheme_name, field:, in:, **other_info
+        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)
         end

data/lib/open_api/dsl.rb

@@ -26,7 +26,7 @@ module OpenApi
       def components &block
         apis_tag if @_ctrl_infos.nil?
         current_ctrl = @_ctrl_infos[:components] = Components.new
-        current_ctrl.instance_eval(&block)
+        current_ctrl.instance_exec(&block)
         current_ctrl.process_objs
       end
 
@@ -41,25 +41,22 @@ module OpenApi
                         .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.instance_eval(&block) if block_given?
+        api.instance_exec(&block) if block_given?
         api.process_objs
         api.delete_if { |_, v| v.blank? }
 
         path = (@_api_infos ||= { })[routes_info[:path]] ||= { }
-        http_verbs = (http || routes_info[:http_verb]).split('|')
-        http_verbs.each { |verb| path[verb] = api }
+        (http || routes_info[:http_verb]).split('|').each { |verb| path[verb] = api }
         api
       end
 
       # method could be symbol array, like: %i[ .. ]
       def api_dry action = :all, desc = '', &block
         @_api_dry_blocks ||= { }
-        if action.is_a? Array
-          action.each { |m| (@_api_dry_blocks[m.to_sym] ||= [ ]) << block }
-        else
-          (@_api_dry_blocks[action.to_sym] ||= [ ]) << block
-        end
+        Array(action).each { |a| (@_api_dry_blocks[a.to_sym] ||= [ ]) << block }
       end
 
       def ctrl_routes_list

data/lib/open_api/dsl/api_info_obj.rb

@@ -19,9 +19,9 @@ module OpenApi
         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!
+      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
@@ -33,14 +33,24 @@ module OpenApi
         return if param_use.present? && param_use.exclude?(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?
+        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
         fill_in_parameters(param_obj)
       end
 
+      # [ header header! path path! query query! cookie cookie! ]
+      def _param_agent name, type = nil, one_of: nil, all_of: nil, any_of: nil, not: nil, **schema_hash
+        combined_schema = one_of || all_of || any_of || (_not = binding.local_variable_get(:not))
+        type = schema_hash[:type] ||= type
+        pp "[ZRO] Syntax Error: param `#{name}` has no schema type!" and return if type.nil? && combined_schema.nil?
+
+        schema_hash = CombinedSchema.new(one_of: one_of, all_of: all_of, any_of: any_of, _not: _not) if combined_schema
+        param @param_type.to_s.delete('!'), name, type, (@param_type['!'] ? :req : :opt), schema_hash
+      end
+
       # For supporting this: (just like `form '', data: { }` usage)
       #   do_query by: {
       #     :search_type => { type: String  },
@@ -49,19 +59,12 @@ module OpenApi
       %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('!').to_sym, value.delete(:type), value ]
-            key.to_s['!'] ? send("#{param_type}!", *args) : send(param_type, *args)
+            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)
           end
-        end unless param_type.to_s['!']
-      end
-
-      def _param_agent name, type = nil, one_of: nil, all_of: nil, any_of: nil, not: nil, **schema_hash
-        (schema_hash = type) and (type = type.delete(:type)) if type.is_a?(Hash) && type.key?(:type)
-        type = schema_hash[:type] if type.nil?
-
-        combined_schema = one_of || all_of || any_of || (_not = binding.local_variable_get(:not))
-        schema_hash = CombinedSchema.new(one_of: one_of, all_of: all_of, any_of: any_of, _not: _not) if combined_schema
-        param "#{@param_type}".delete('!'), name, type, (@param_type['!'] ? :req : :opt), schema_hash
+        end
       end
 
       def param_ref component_key, *keys
@@ -75,18 +78,13 @@ module OpenApi
         self[:requestBody].add_or_fusion(media_type, options.merge(data: data))
       end
 
+      # [ body body! ]
       def _request_body_agent media_type, data: { }, **options
         request_body (@method_name['!'] ? :req : :opt), media_type, data: data, **options
       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][code] = RefObj.new(:response, component_key).process
-        end
+        self[:requestBody] = RefObj.new(:requestBody, component_key)
       end
 
       def form data:, **options
@@ -110,6 +108,12 @@ module OpenApi
         body! media_type, data: data, **options
       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
+
       def security_require scheme_name, scopes: [ ]
         self[:security] << { scheme_name => scopes }
       end
@@ -118,12 +122,13 @@ module OpenApi
       alias auth      security_require
       alias need_auth security_require
 
-      def server url, desc
+      def server url, desc: ''
         self[:servers] << { url: url, description: desc }
       end
 
       def order *param_names
         self.param_order = param_names
+        # use when api_dry
         self.param_use = param_order if param_use.blank?
         self.param_skip = param_use - param_order
       end
@@ -136,7 +141,6 @@ module OpenApi
 
       alias examples param_examples
 
-
       def process_objs
         self[:parameters]&.each_with_index do |p, index|
           self[:parameters][index] = p.process if p.is_a?(ParamObj)

data/lib/open_api/dsl/components.rb

@@ -7,13 +7,13 @@ module OpenApi
       include DSL::Helpers
 
       def schema component_key, type = nil, one_of: nil, all_of: nil, any_of: nil, not: nil, **schema_hash
-        (schema_hash = type) and (type = type.delete(:type)) if type.is_a?(Hash) && type.key?(:type)
-        type ||= schema_hash[:type]
-        type ||= load_schema component_key if component_key.try(:superclass) == Config.active_record_base || ApplicationRecord
-
         combined_schema = (_not = binding.local_variable_get(:not)) || one_of || all_of || any_of
+        schema_hash[:type] ||= type
+        schema_hash = load_schema component_key if component_key.try(:superclass) == (Config.active_record_base || ApplicationRecord)
+        pp "[ZRO] Syntax Error: component schema `#{component_key}` has no type!" and return if schema_hash[:type].nil? && combined_schema.nil?
+
         combined_schema = CombinedSchema.new(one_of: one_of, all_of: all_of, any_of: any_of, _not: _not) if combined_schema
-        (self[:schemas] ||= { })[component_key.to_s.to_sym] = combined_schema&.process || SchemaObj.new(type, schema_hash).process
+        (self[:schemas] ||= { })[component_key.to_s.to_sym] = combined_schema&.process || SchemaObj.new(schema_hash, { }).process
       end
       arrow_enable :schema
 
@@ -26,9 +26,11 @@ module OpenApi
         (self[:parameters] ||= { })[component_key] = ParamObj.new(name, param_type, type, required, schema_hash).process
       end
 
+      # [ header header! path path! query query! cookie cookie! ]
       def _param_agent component_key, name, type = nil, one_of: nil, all_of: nil, any_of: nil, not: nil, **schema_hash
-        (schema_hash = type) and (type = type.delete(:type)) if type.is_a?(Hash) && type.key?(:type)
-        type = schema_hash[:type] if type.nil?
+        combined_schema = one_of || all_of || any_of || (_not = binding.local_variable_get(:not))
+        schema_hash[:type] ||= type
+        pp "[ZRO] Syntax Error: param `#{name}` has no schema type!" and return if schema_hash[:type].nil? && combined_schema.nil?
 
         combined_schema = one_of || all_of || any_of || (_not = binding.local_variable_get(:not))
         schema_hash = CombinedSchema.new(one_of: one_of, all_of: all_of, any_of: any_of, _not: _not) if combined_schema
@@ -44,6 +46,7 @@ module OpenApi
         self[:requestBodies][component_key] = cur.add_or_fusion(media_type, options.merge(data: data))
       end
 
+      # [ body body! ]
       def _request_body_agent component_key, media_type, data: { }, **options
         request_body component_key,
                      (@method_name['!'] ? :req : :opt), media_type, data: data, **options
@@ -71,7 +74,7 @@ module OpenApi
       end
       arrow_enable :bearer_auth
 
-      def api_key scheme_name, field:, in:, **other_info
+      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)
       end

data/lib/open_api/dsl/helpers.rb

@@ -5,6 +5,7 @@ module OpenApi
         base.extend ClassMethods
       end
 
+      # :nocov:
       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
@@ -37,6 +38,7 @@ module OpenApi
           end rescue next
         end
       end
+      # :nocov:
 
       def fill_in_parameters(param_obj)
         name = param_obj.processed[:name]

data/lib/open_api/generator.rb

@@ -8,17 +8,17 @@ module OpenApi
 
     module ClassMethods
       def generate_docs(doc_name = nil)
+        pp '[ZRO] No documents have been configured!' and return if Config.docs.keys.blank?
+
         Dir['./app/controllers/**/*_controller.rb'].each do |file|
           # Do Not `require`!
           #   It causes problems, such as making `skip_before_action` not working.
+          # :nocov:
           file.sub('./app/controllers/', '').sub('.rb', '').camelize.constantize
+          # :nocov:
         end
         Dir[*Array(Config.doc_location)].each { |file| require file }
-        if doc_name.present?
-          [{ doc_name => generate_doc(doc_name) }]
-        else
-          Config.docs.keys.map { |api_key| { api_key => generate_doc(api_key) } }.reduce({ }, :merge)
-        end
+        (doc_name || Config.docs.keys).map { |name| { name => generate_doc(name) } }.reduce({ }, :merge)
       end
 
       def generate_doc(doc_name)
@@ -42,12 +42,13 @@ module OpenApi
         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] = ActiveSupport::HashWithIndifferentAccess.new(doc.delete_if { |_, v| v.blank? })
       end
 
       def write_docs(generate_files: true)
         docs = generate_docs
         return unless generate_files
+        # :nocov:
         output_path = Config.file_output_path
         FileUtils.mkdir_p output_path
         max_length = docs.keys.map(&:size).sort.last
@@ -56,6 +57,7 @@ module OpenApi
           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
 
@@ -64,12 +66,14 @@ module OpenApi
         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
 
       @routes_list ||= routes.split("\n").drop(1).map do |line|

data/lib/open_api/version.rb

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

data/zero-rails_openapi.gemspec

@@ -1,32 +1,33 @@
 
-lib = File.expand_path("../lib", __FILE__)
+lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require "open_api/version"
+require 'open_api/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "zero-rails_openapi"
+  spec.name          = 'zero-rails_openapi'
   spec.version       = OpenApi::VERSION
-  spec.authors       = ["zhandao"]
-  spec.email         = ["x@skippingcat.com"]
+  spec.authors       = ['zhandao']
+  spec.email         = ['x@skippingcat.com']
 
-  spec.summary       = %q{Concise DSL for generating OpenAPI3 documentation.}
-  spec.description   = %q{Concise DSL for generating OpenAPI Specification 3 (OAS3) JSON documentation for Rails application.}
-  spec.homepage      = "https://github.com/zhandao/zero-rails_openapi"
-  spec.license       = "MIT"
+  spec.summary       = 'Concise DSL for generating OpenAPI3 documentation.'
+  spec.description   = 'Concise DSL for generating OpenAPI Specification 3 (OAS3) JSON documentation for Rails application.'
+  spec.homepage      = 'https://github.com/zhandao/zero-rails_openapi'
+  spec.license       = 'MIT'
 
   spec.files         = `git ls-files -z`.split("\x0").reject do |f|
     f.match(%r{^(test|spec|features)/})
   end
-  spec.bindir        = "exe"
+  spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
 
-  spec.add_development_dependency "bundler", "~> 1.16.a"
-  spec.add_development_dependency "rake", "~> 10.0"
-  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency 'bundler', '~> 1.16.a'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'simplecov'
 
-  spec.add_runtime_dependency "rails", ">= 3"
-  spec.add_runtime_dependency "activesupport", ">= 3"
+  spec.add_runtime_dependency 'rails', '>= 3'
+  spec.add_runtime_dependency 'activesupport', '>= 3'
 
   # spec.post_install_message = ""
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zero-rails_openapi
 version: !ruby/object:Gem::Version
-  version: 1.4.3
+  version: 1.5.1
 platform: ruby
 authors:
 - zhandao
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-12-12 00:00:00.000000000 Z
+date: 2017-12-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,6 +52,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
@@ -150,7 +164,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.13
+rubygems_version: 2.6.12
 signing_key: 
 specification_version: 4
 summary: Concise DSL for generating OpenAPI3 documentation.