zero-rails_openapi 1.4.2 → 1.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5f96bf52633bfd7fe91394003f64571c24bfc4ad
-  data.tar.gz: f44d8713d0691eacd66ae9a5ff62f90f21b97595
+  metadata.gz: fefcfd0fc562daad7532e1dadd0121e8c30c0adb
+  data.tar.gz: 25cf51020674fce5fb428f6b121b6c6a25c02c72
 SHA512:
-  metadata.gz: 9ad13a356350c385963ac5a62233afc6f4a182360b6684e2536782ffaadb86d4458112844ec44eff8055adf5c1957c2dd2ac92b32c906445c221de17693aa34a
-  data.tar.gz: 1dc8b8bb3002a33ac62ab4016fb2359e72a4ce1e43b378c520cf3dbd40dd43227162e43a31801ef824a02323b1fbe5c9f9cdeb51cfe42cb6ee7ba6d3cc174cab
+  metadata.gz: 77306d030cba3bfbcb7f6d31eaac31c9ed7dd60355a012166a040633cd6420ebe898b483dcef1fae571da47fcb64871489da7c91069014246dd788e78c2e0815
+  data.tar.gz: 5ad12c05afbf059b177bc1e797e401f49595d7be696e386f89b6e1f945daa511ebc2919c2564b4439e07c0951147682c3ee116efc0f9de4708f845e8e06327b8

data/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Version Changelog
 
+## [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
+
+1. `example` method in `components` block.
+2. Request Body (also Response):
+    1. The same media-types will be fusion together.  
+       (This means you can write `form` separately.)
+    2. Different media-types will not be replaced, all will be merged in `content`.
+    3. Support flat statement form-data by `data`.
+
+### Fixed
+
+1. `generate_doc` raise 'should not nil when merge' if settings[:components] not set.
+2. `@preprocessed not initialize` warning.
+
+### Added
+
+1. Schema option `blankable`.
+2. Schema option alias `in` to `enum`.
+3. Schema option `pattern` could be `String` for supporting Time Format.
+
+### Changed
+
+1. `form` mandatory requirements pass `data: { }`.
+2. Remove `request_body`'s parameter `desc` to `**options`.
+3. Remove aliases of `response`.
 
 ## [1.4.1] - 2017/12/6 - [view diff](https://github.com/zhandao/zero-rails_openapi/compare/v1.4.0...v1.4.1)
 
@@ -52,7 +79,7 @@
 2. Support designated http method in `api`.
 3. The completion of the basic README.
 
-## [1.3.2 & 1.3.3] - 2017/11/10,21 - [view diff](https://github.com/zhandao/zero-rails_openapi/compare/v1.3.1...v1.3.3)
+## [1.3.2 & 1.3.3] - 2017/11/10&21 - [view diff](https://github.com/zhandao/zero-rails_openapi/compare/v1.3.1...v1.3.3)
 
 ### Feature
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    zero-rails_openapi (1.4.2)
+    zero-rails_openapi (1.4.3)
       activesupport (>= 3)
       rails (>= 3)
 

data/README.md

@@ -22,8 +22,8 @@
 - [Usage - DSL](#usage---dsl)
   - [DSL methods inside `api` and `api_dry`'s block](#dsl-methods-inside-api-and-api_drys-block)
   - [DSL methods inside `components`'s block](#dsl-methods-inside-componentss-block-code-source)
-- [Usage - Generate JSON documentation file](#usage---generate-json-documentation-file)
-- [Usage - Use Swagger UI(very beautiful web page) to show your Documentation](#usage---use-swagger-uivery-beautiful-web-page-to-show-your-documentation)
+- [Run! - Generate JSON documentation file](#run---generate-json-documentation-file)
+- [Use Swagger UI(very beautiful web page) to show your Documentation](#use-swagger-uivery-beautiful-web-page-to-show-your-documentation)
 - [Tricks](#tricks)
     - [Write DSL somewhere else](#trick1---write-the-dsl-somewhere-else)
     - [Global DRYing](#trick2---global-drying)
@@ -370,16 +370,18 @@
                 #   it links sepcified RefObjs (by component keys) to current body.
   body, body!   # alias of request_body
   form, form!   # define a multipart/form-data body
+  data          # define [a] property in the form-data body
   file, file!   # define a File media-type body
   ```
-  
+  Bang methods(!) means the specified media-type body is required.
+
   ```ruby
   # method signature
-  request_body(is_required, media_type, desc = '', schema_hash = { })
+  request_body(required, media_type, data: { }, **options)
   # usage
-  request_body :opt, :form, '', type: { id!: Integer, name: String }
-  # or
-  request_body :opt, :form, '', data: { id!: Integer, name: String }
+  # (1) `data` contains all the attributes required by this request body.
+  # (2) `param_name!` means it is required, otherwise without '!' means optional.
+  request_body :opt, :form, data: { id!: Integer, name: { type: String, desc: 'name' } }, desc: 'form-data'
 
 
   # method signature
@@ -389,23 +391,23 @@
 
 
   # method signature
-  body!(media_type, desc = '', schema_hash = { })
+  body!(media_type, data: { }, **options)
   # usage
   body :json
   
   
   # method implement
-  def form desc = '', schema_hash = { }
-    body :form, desc, schema_hash
+  def form data:, **options
+    body :form, data: data, **options
   end
   # usage
-  form! 'register', data: {
+  form! data: {
           name: String,
           password: String,
           password_confirmation: String
       }
   # advance usage
-  form 'for creating a user', data: {
+  form data: {
               :name! => { type: String, desc: 'user name' },
           :password! => { type: String, pattern: /[0-9]{6,10}/, desc: 'password' },
           # optional
@@ -414,62 +416,77 @@
          examples: {         #    ↓        ↓
              :right_input => [ 'user1', '123456' ],
              :wrong_input => [ 'user2', 'abc'    ]
-         }
-
+         },
+      desc: 'for creating a user'
+  
+  
+  # method implement
+  def data name, type = nil, schema_hash = { }
+    schema_hash[:type] = type if type.present?
+    form data: { name => schema_hash }
+  end
+  # usage: please look at the 4th point below
 
   # about `file`
-  def file! media_type, desc = '', schema_hash = { type: File }
-    body! media_type, desc, schema_hash
+  def file! media_type, data: { type: File }, **options
+    body! media_type, data: data, **options
   end
   ```
   
-  1. **Notice:** Each API should only declare a request body
-     That is, all of the above methods you can only choose one of them.  
-     (But **multiple media types** will be supported in the future).
-  2. `media_type`: we provide some [mapping](lib/oas_objs/media_type_obj.rb) from symbols to real media-types.  
-  3. `schema_hash`: as above (see param).  
-     **One thing that should be noted is: when use Hash writing, `scham_type` is writed in schema_hash using key :type.**
-  4. `exp_by` and `examples`: for the above example, the following has the same effect:
+  1. `media_type`: we provide some [mapping](lib/oas_objs/media_type_obj.rb) from symbols to real media-types.  
+  2. `schema_hash`: as above (see param).  
+  3. `exp_by` and `examples`: for the above example, the following has the same effect:
      ```
      examples: {
          :right_input => { name: 'user1', password: '123456' },
          :wrong_input => { name: 'user2', password: 'abc' }
      }
      ```
+  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: { }
+     # will generate: "content": { "multipart/form-data": { }, "application/json": { } }
+     ```
+     (2) The same media-types will fusion, but not merge:  
+         (So that you can write `form` separately, and make `data` method possible.)
+     ```ruby
+     data :param_a!, String
+     data :param_b,  Integer
+     # or same as:
+     form '', data: { :param_a! => String }
+     form '', data: { :param_b  => Integer }
+     # will generate: { "param_a": { "type": "string" }, "param_b": { "type": "integer" } } (call it X)
+     # therefore:
+     #   "content": { "multipart/form-data": 
+     #     { "schema": { "type": "object", "properties": { X }, "required": [ "param_a" ] } 
+     #   }
+     ```
   
 #### (5) `response` family methods (OAS - [Response Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#response-object))
   
   Define the responses for the API (action).
   ```
-  response or resp
+  response      # aliases: `resp` and `error`
   response_ref
-  default_response or dft_resp
-  error_response, other_response, oth_resp, error, err_resp # response's aliases, should be used in the error response context.
-  merge_to_resp
   ```
   
   ```ruby
   # method signature
-  response(response_code, desc, media_type = nil, schema_hash = { })
+  response(code, desc, media_type = nil, data: { }, type: nil)
   # usage
   response 200, 'query result', :pdf, type: File
+  # same as:
+  response 200, 'query result', :pdf, data: File
 
   # method signature
   response_ref(code_compkey_hash)
   # usage
   response_ref 700 => :AResp, 800 => :BResp
-
-  # method signature
-  merge_to_resp(code, by:)
-  # usage
-  merge_to_resp 200, by: {
-      data: {
-          type: String
-      }
-  }
   ```
   
-  **practice:** Combined with wrong class, automatically generate error responses. [AutoGenDoc](documentation/examples/auto_gen_doc.rb#L63)  
+  **practice:** Automatically generate responses based on the agreed error class. [AutoGenDoc](documentation/examples/auto_gen_doc.rb#L63)  
   
 #### (6) Authentication and Authorization
   
@@ -541,11 +558,11 @@
 ### DSL methods inside [components]()'s block ([code source](lib/open_api/dsl/components.rb))
 
   (Here corresponds to OAS [Components Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#componentsObject))
-  
+
   Inside `components`'s block,
   you can use the same DSL as [[DSL methods inside `api` and `api_dry`'s block]](#dsl-methods-inside-api-and-api_drys-block).
   But there are two differences:  
-  
+
   (1) Each method needs to pass one more parameter `component_key`
     (in the first parameter position),
     this will be used as the reference name for the component.
@@ -560,9 +577,9 @@
   ```ruby
   query! :UidQuery => [:uid, String]
   ```
-  
+
   (2) You can use `schema` to define a Schema Component.
-  
+
   ```ruby
   # method signature
   schema(component_key, type = nil, one_of: nil, all_of: nil, any_of: nil, not: nil, **schema_hash)
@@ -585,8 +602,8 @@
   schema User # easy! And the component_key will be :User
   ```
   [1] see: [Type](documentation/parameter.md#type-schema_type)
-  
-## Usage - Generate JSON Documentation File
+
+## Run! - Generate JSON Documentation File
 
   Use `OpenApi.write_docs`:
   
@@ -600,7 +617,7 @@
   
   Then the JSON files will be written to the directories you set. (Each API a file.)
 
-## Usage - Use Swagger UI(very beautiful web page) to show your Documentation
+## Use Swagger UI(very beautiful web page) to show your Documentation
 
   Download [Swagger UI](https://github.com/swagger-api/swagger-ui) (version >= 2.3.0 support the OAS3) 
   to your project,  

data/README_zh.md

@@ -24,8 +24,8 @@
 - [DSL 介绍及用例](#usage---dsl)
   - [用于 `api` 和 `api_dry` 块内的 DSL（描述 API 的参数、响应等）](#dsl-methods-inside-api-and-api_drys-block)
   - [用于 `components` 块内的 DSL（描述可复用的组件）](#dsl-methods-inside-componentss-block-code-source)
-- [执行文档生成](#usage---generate-json-documentation-file)
-- [使用 Swagger-UI 可视化所生成的文档](#usage---use-swagger-uivery-beautiful-web-page-to-show-your-documentation)
+- [执行文档生成](#run---generate-json-documentation-file)
+- [使用 Swagger-UI 可视化所生成的文档](#use-swagger-uivery-beautiful-web-page-to-show-your-documentation)
 - [技巧](#tricks)
     - [将 DSL 写于他处，与控制器分离](#trick1---write-the-dsl-somewhere-else)
     - [全局 DRY](#trick2---global-drying)
@@ -580,7 +580,7 @@
   ```
   [1] see: [Type](documentation/parameter.md#type-schema_type)
 
-## Usage - Generate JSON Documentation File
+## Run! - Generate JSON Documentation File
 
   Use `OpenApi.write_docs`:
   
@@ -594,7 +594,7 @@
   
   Then the JSON files will be written to the directories you set. (Each API a file.)
 
-## Usage - Use Swagger UI(very beautiful web page) to show your Documentation
+## Use Swagger UI(very beautiful web page) to show your Documentation
 
   Download [Swagger UI](https://github.com/swagger-api/swagger-ui) (version >= 2.3.0 support the OAS3) 
   to your project,  

data/documentation/examples/auto_gen_doc.rb

@@ -50,7 +50,7 @@ module AutoGenDoc
           # default_response 'default response', :json
           model = Object.const_get(action_path.split('#').first.split('/').last[0..-2].camelize) rescue nil
           type = action.in?(%w[ index show ]) ? Array[load_schema(model)] : String
-          response '200', 'success', :json, type: {
+          response '200', 'success', :json, data: {
               code: { type: Integer, dft: 200 },
                msg: { type: String,  dft: 'success' },
               data: { type: type }

data/documentation/examples/examples_controller.rb

@@ -30,20 +30,16 @@ class Api::V1::ExamplesController < Api::V1::BaseController
 
     query :test_type, type: String
     query :combination, one_of: [ :DogSchema, String, { type: Integer, desc: 'integer input'}]
-    form '', data: {
+    form data: {
         :combination => { any_of: [ Integer, String ] }
     }
 
-    response :success, 'success response', :json, type: :DogSchema
-    merge_to_resp 200, by: {
-        data: {
-            type: [
-                String
-            ]
-        }
-    }
+    response :success, 'success response', :json#, data: :Pet
+    security :Token
 
-    security :ApiKeyAuth
+    resp 200, '', :json, data: {
+        a: String
+    }
   end
 
 
@@ -54,7 +50,7 @@ class Api::V1::ExamplesController < Api::V1::BaseController
 
 
   api :create do
-    form 'for creating a user', data: {
+    form! data: {
             :name! => String, # <= schema_type is `String`
         :password! => { type: String, pattern: /[0-9]{6,10}/, desc: 'password' },
         # optional

data/documentation/examples/goods_doc.rb

@@ -28,7 +28,7 @@ class V2::GoodsDoc < BaseDoc
 
 
   api :create, 'POST create a good', use: 'Token' do
-    form! 'for creating a good', data: {
+    form! data: {
                :name! => { type: String,  desc: 'good\'s name' },
         :category_id! => { type: Integer, desc: 'sub_category\'s id', npmt: true, range: { ge: 1 }, as: :cate  },
               :price! => { type: Float,   desc: 'good\'s price', range: { ge: 0 } },

data/documentation/parameter.md

@@ -62,6 +62,7 @@ You can set the schema by following keys (all are optional), the words in parent
     for example the parameter name "user_email" will generate "is: email". Default `is` options are:  
     [email phone password uuid uri url time date], to overwrite it you can set it in initializer `c.is_options = %w[]`.
     5. If type is Object, for describing each property's schema, the only way is use ref type, like: `{ id: :Id, name: :Name }`
-  - **pattern (regexp, pr, reg)**
+  - **pattern (regexp, pr, reg)**  
+  Regexp or Time Format
   - **default (dft, default_value)**
   - **as** # TODO

data/lib/oas_objs/combined_schema.rb

@@ -14,12 +14,12 @@ module OpenApi
       end
 
       def process_for(param_name = nil, options = { desc_inside: false })
-        processed.tap do |it|
-          it[@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) end
+        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)
         end
+        processed
       end
 
       alias process process_for

data/lib/oas_objs/helpers.rb

@@ -1,5 +1,21 @@
 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
+    end
+
     def truly_present?(obj)
       obj == false || obj.present?
     end
@@ -14,7 +30,7 @@ module OpenApi
       self
     end
 
-    # reduceee.then_merge! => for Hash
+    # reducx.then_merge! => for Hash
     def reducx(*values)
       @assign = values.compact.reduce({ }, :merge).keep_if &value_present
       self

data/lib/oas_objs/request_body_obj.rb

@@ -8,14 +8,19 @@ module OpenApi
     class RequestBodyObj < Hash
       include Helpers
 
-      attr_accessor :processed, :media_type
-      def initialize(required, media_type, desc, hash)
-        self.media_type = MediaTypeObj.new(media_type, hash)
-        self.processed  = { required: required.to_s.match?(/req/), description: desc }
+      attr_accessor :processed, :media_types
+      def initialize(required, desc)
+        self.media_types = [ ]
+        self.processed   = { required: required.match?('req'), description: desc }
+      end
+
+      def add_or_fusion(media_type, hash)
+        media_types << MediaTypeObj.new(media_type, hash)
+        self
       end
 
       def process
-        assign(media_type.process).to_processed 'content'
+        assign(media_types.map(&:process).reduce({ }, &fusion)).to_processed 'content'
         processed
       end
     end

data/lib/oas_objs/response_obj.rb

@@ -7,17 +7,19 @@ module OpenApi
     class ResponseObj < Hash
       include Helpers
 
-      attr_accessor :processed, :code, :media_type
-      def initialize(desc, media_type, hash)
-        @hash = hash
-        @mt = media_type
-        self.code       = code.to_s
-        self.media_type = MediaTypeObj.new(media_type, hash)
-        self.processed  = { description: desc }
+      attr_accessor :processed, :media_types
+      def initialize(desc)
+        self.media_types = [ ]
+        self.processed   = { description: desc }
+      end
+
+      def add_or_fusion(media_type, hash)
+        media_types << MediaTypeObj.new(media_type, hash)
+        self
       end
 
       def process
-        assign(media_type.process).to_processed 'content'
+        assign(media_types.map(&:process).reduce({ }, &fusion)).to_processed 'content'
         processed
       end
 

data/lib/oas_objs/schema_obj.rb

@@ -30,17 +30,17 @@ module OpenApi
       def process_for(param_name = nil, options = { desc_inside: false })
         return processed if @preprocessed
 
-        processed.merge! processed_type
+        processed.merge!(processed_type)
         reducx(
             processed_enum_and_length,
             processed_range,
             processed_is_and_format(param_name),
             {
-                pattern:    _pattern&.inspect&.delete('/'),
-                default:    _default.nil? ? nil : '_default',
+                pattern:    _pattern.is_a?(String)? _pattern : _pattern&.inspect&.delete('/'),
+                default:    nil,
                 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 }
+            { 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?
 
@@ -69,7 +69,7 @@ module OpenApi
           recursive_array_type(t)
         elsif t.is_a? Symbol
           RefObj.new(:schema, t).process
-        elsif t.in? %w[float double int32 int64] # to README: 这些值应该传 string 进来, symbol 只允许 $ref
+        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}
@@ -142,7 +142,7 @@ module OpenApi
 
 
       { # SELF_MAPPING
-          _enum:    %i[ enum     values  allowable_values ],
+          _enum:    %i[ enum in  values  allowable_values ],
           _value:   %i[ must_be  value   allowable_value  ],
           _range:   %i[ range    number_range             ],
           _length:  %i[ length   lth     size             ],
@@ -157,6 +157,7 @@ module OpenApi
           _npermit: %i[ npmt     not_permit   unpermit    ], # NOT OAS Spec, it's for zero-params_processor
           _req_if:  %i[ req_if   req_when                 ], # NOT OAS Spec, it's for zero-params_processor
           _opt_if:  %i[ opt_if   opt_when                 ], # NOT OAS Spec, it's for zero-params_processor
+          _blank:   %i[ blank    blankable                ], # NOT OAS Spec, it's for zero-params_processor
       }.each do |key, aliases|
         define_method key do
           return self[key] unless self[key].nil?

data/lib/open_api/dsl.rb

@@ -27,7 +27,7 @@ module OpenApi
         apis_tag if @_ctrl_infos.nil?
         current_ctrl = @_ctrl_infos[:components] = Components.new
         current_ctrl.instance_eval(&block)
-        current_ctrl._process_objs
+        current_ctrl.process_objs
       end
 
       def api action, summary = '', http: nil, skip: [ ], use: [ ], &block
@@ -43,7 +43,7 @@ module OpenApi
         [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.instance_eval(&block) if block_given?
-        api._process_objs
+        api.process_objs
         api.delete_if { |_, v| v.blank? }
 
         path = (@_api_infos ||= { })[routes_info[:path]] ||= { }

data/lib/open_api/dsl/api_info_obj.rb

@@ -38,8 +38,7 @@ module OpenApi
 
         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
+        fill_in_parameters(param_obj)
       end
 
       # For supporting this: (just like `form '', data: { }` usage)
@@ -69,45 +68,46 @@ module OpenApi
         self[:parameters].concat([component_key].concat(keys).map { |key| RefObj.new(:parameter, key).process })
       end
 
-      def request_body required, media_type, desc = '', hash = { }
-        self[:requestBody] = RequestBodyObj.new(required, media_type, desc, hash).process
+      # options: `exp_by` and `examples`
+      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))
       end
 
-      def _request_body_agent media_type, desc = '', hash = { }
-        request_body (@method_name['!'] ? :req : :opt), media_type, desc, hash
+      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 merge_to_resp code, by:
-        _response = self[:responses].fetch(code)
-        self[:responses][code] = _response.override(by).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 = '', hash = { }
-        body :form, desc, hash
+      def form data:, **options
+        body :form, data: data, **options
       end
 
-      def form! desc = '', hash = { }
-        body! :form, desc, hash
+      def form! data:, **options
+        body! :form, data: data, **options
       end
 
-      # TODO: 这种情况下 form 和 file 无法共存，需要解决（通过 combined?）
-      def file media_type, desc = '', hash = { type: File }
-        body media_type, desc, hash
+      def data name, type = nil, schema_hash = { }
+        schema_hash[:type] = type if type.present?
+        form data: { name => schema_hash }
       end
 
-      def file! media_type, desc = '', hash = { type: File }
-        body! media_type, desc, hash
+      def file media_type, data: { type: File }, **options
+        body media_type, data: data, **options
+      end
+
+      def file! media_type, data: { type: File }, **options
+        body! media_type, data: data, **options
       end
 
       def security_require scheme_name, scopes: [ ]
@@ -129,7 +129,7 @@ module OpenApi
       end
 
       def param_examples exp_by = :all, examples_hash
-        _process_objs
+        process_objs
         exp_by = self[:parameters].map { |p| p[:name] } if exp_by == :all
         self[:examples] = ExampleObj.new(examples_hash, exp_by).process
       end
@@ -137,7 +137,7 @@ module OpenApi
       alias examples param_examples
 
 
-      def _process_objs
+      def process_objs
         self[:parameters]&.each_with_index do |p, index|
           self[:parameters][index] = p.process if p.is_a?(ParamObj)
         end
@@ -147,6 +147,8 @@ module OpenApi
           self[:parameters][param_order.index(p[:name]) || -1] = p
         end if param_order.present?
 
+        self[:requestBody] = self[:requestBody].try :process
+
         self[:responses]&.each do |code, obj|
           self[:responses][code] = obj.process if obj.is_a?(ResponseObj)
         end

data/lib/open_api/dsl/common_dsl.rb

@@ -25,23 +25,13 @@ module OpenApi
       end
 
       # `code`: when defining components, `code` means `component_key`
-      def response code, desc, media_type = nil, hash = { }
-        (self[:responses] ||= { })[code] = ResponseObj.new(desc, media_type, hash)
+      def response code, desc, media_type = nil, data: { }, type: nil
+        self[:responses][code] = ResponseObj.new(desc) unless (self[:responses] ||= { })[code].is_a?(ResponseObj)
+        self[:responses][code].add_or_fusion(media_type, { data: type || data })
       end
 
-      def default_response desc, media_type = nil, hash = { }
-        response :default, desc, media_type, 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
+      alias_method :resp,  :response
+      alias_method :error, :response
     end
   end
 end

data/lib/open_api/dsl/components.rb

@@ -37,13 +37,16 @@ module OpenApi
       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
+      def request_body component_key, required, media_type, data: { }, **options
+        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))
       end
 
-      def _request_body_agent component_key, media_type, desc = '', schema_hash = { }
+      def _request_body_agent component_key, media_type, data: { }, **options
         request_body component_key,
-                     (@method_name['!'] ? :req : :opt), media_type, desc, schema_hash
+                     (@method_name['!'] ? :req : :opt), media_type, data: data, **options
       end
       arrow_enable :_request_body_agent
 
@@ -74,7 +77,11 @@ module OpenApi
       end
       arrow_enable :api_key
 
-      def _process_objs
+      def process_objs
+        self[:requestBodies]&.each do |key, obj|
+          self[:requestBodies][key] = obj.process
+        end
+
         self[:responses]&.each do |code, obj|
           self[:responses][code] = obj.process if obj.is_a?(ResponseObj)
         end

data/lib/open_api/dsl/helpers.rb

@@ -38,6 +38,12 @@ module OpenApi
         end
       end
 
+      def fill_in_parameters(param_obj)
+        name = param_obj.processed[:name]
+        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
+
       # Arrow Writing:
       #   response :RespComponent => [ '200', 'success', :json ]
       # It is equivalent to:

data/lib/open_api/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zero-rails_openapi
 version: !ruby/object:Gem::Version
-  version: 1.4.2
+  version: 1.4.3
 platform: ruby
 authors:
 - zhandao
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-12-10 00:00:00.000000000 Z
+date: 2017-12-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler