Changes:

1. Support designated http method in `open_api`.
2. Support multi-httpverbs.
3. Support both type and type:.

Author: hikari-desu

LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2017 will.huang
+Copyright (c) 2017 zhandao
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -28,7 +28,7 @@
     - [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---auto-generate-indexshow-actionss-responses-based-on-db-schema)
+    - [Atuo Generate index/show Actions's Responses Based on DB Schema](#trick5---auto-generate-indexshow-actionss-response-types-based-on-db-schema)
 - [Troubleshooting](#troubleshooting)
 
 ## About OAS
@@ -232,7 +232,7 @@
 
 ### DSL methods inside [open_api]() and [api_dry]()'s block
 
-  [source code](lib/open_api/dsl_inside_block.rb), ApiInfoObj
+  [source code](lib/open_api/dsl/api_info_obj.rb)
 
   These following methods in the block describe the specified API action: description, valid?,
   parameters, request body, responses, securities, servers.
@@ -305,14 +305,23 @@
 
 
   # method signature
-   header(param_name, schema_type, schema_hash = { })
-  header!(param_name, schema_type, schema_hash = { })
-   query!(param_name, schema_type, schema_hash = { })
+   header(param_name, schema_type = nil, schema_hash = { })
+  header!(param_name, schema_type = nil, schema_hash = { })
+   query!(param_name, schema_type = nil, schema_hash = { })
   # usage
   header! 'Token', String
   query!  :readed, Boolean, must_be: true, default: false
   # The same effect as above, but not simple
-  param   :query, :readed, Boolean, :req, must_be: true, default: false
+  param :query, :readed, Boolean, :req, must_be: true, default: false
+  #
+  # When schema_type is a Object 
+  #   (describe by hash, key means prop's name, value means prop's schema_type)
+  query :good, { name: String, price: Float, spec: { size: String, weight: Integer } }, desc: 'good info'
+  # Or you can use `type:` to sign the schema_type, maybe this is clearer for describing object
+  query :good, type: { name: String, price: Float, spec: { size: String, weight: Integer } }, desc: 'good info'
+  #
+  query :good_name, type: String # It's also OK, but some superfluous
+  query :good_name, String       # recommended
 
 
   # method signature
@@ -457,7 +466,7 @@
 
 #### (7) `server`: TODO
 
-### DSL methods inside [components]()'block ([code source](lib/open_api/dsl_inside_block.rb):: CtrlInfoObj )
+### DSL methods inside [components]()'block ([code source](lib/open_api/dsl/ctrl_info_obj.rb):: CtrlInfoObj )
 
   (Here corresponds to OAS [Components Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#componentsObject))
 
@@ -492,7 +501,7 @@
   # or (unrecommended)
   schema :Dog, { id!: Integer, name: String }, dft: { id: 1, name: 'pet' }, desc: 'dogee'
   ```
-  [1] see: [Type](documentation/parameter.md#type)
+  [1] see: [Type](documentation/parameter.md#type-schema_type)
 
 ## Usage - Generate JSON Documentation File
 

lib/oas_objs/schema_obj.rb

@@ -185,7 +185,7 @@ def processed_is_and_format(name)
       def recognize_is_options_in(name)
         # 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}/
+          self._is = pattern or break if name.match?(/#{pattern}/)
         end if _is.nil?
       end
 

lib/open_api/dsl.rb

@@ -30,40 +30,35 @@ def components &block
         current_ctrl._process_objs
       end
 
-      def open_api action, summary = '', builder: nil, skip: [ ], use: [ ], &block
+      def open_api action, summary = '', http: nil, builder: nil, skip: [ ], use: [ ], &block
         apis_tag if @_ctrl_infos.nil?
-
         # select the routing info (corresponding to the current method) from routing list.
         action_path = "#{@_ctrl_path ||= controller_path}##{action}"
-        routes_info = ctrl_routes_list&.select { |api| api[:action_path].match? /^#{action_path}$/ }&.first
+        routes_info = ctrl_routes_list&.select { |api| api[:action_path].match?(/^#{action_path}$/) }&.first
         pp "[ZRO Warning] Routing mapping failed: #{@_ctrl_path}##{action}" and return if routes_info.nil?
-        Generator.generate_builder_file(action_path, builder) if builder.present?
+        Generator.generate_builder_file(action_path, builder)
 
-        # 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, skip: Array(skip), use: Array(use))
-                .merge! description: '', summary: summary, operationId: action, tags: [@_apis_tag],
-                        parameters: [ ], requestBody: '',  responses: { },      security: [ ], servers: [ ]
+        api = ApiInfoObj.new(action_path, skip: Array(skip), use: Array(use))
+                        .merge! description: '', summary: summary, operationId: action, tags: [@_apis_tag],
+                                parameters: [ ], requestBody: '',  responses: { },      security: [ ], servers: [ ]
+        [action, :all].each { |blk_key| @_api_dry_blocks&.[](blk_key)&.each { |blk| api.instance_eval(&blk) } }
+        api.param_use = [ ] # `skip` and `use` only affect `api_dry`'s blocks
+        api.instance_eval(&block) if block_given?
+        api._process_objs
+        api.delete_if { |_, v| v.blank? }
 
-        current_api.tap do |api|
-          [action, :all].each do |key| # blocks_store_key
-            @_apis_blocks&.[](key)&.each { |blk| api.instance_eval(&blk) }
-          end
-          api.param_use = [ ] # skip 和 use 是对 dry 块而言的
-          api.instance_eval(&block) if block_given?
-          api._process_objs
-          api.delete_if { |_, v| v.blank? }
-        end
+        path = (@_api_infos ||= { })[routes_info[:path]] ||= { }
+        http_verbs = (http || routes_info[:http_verb]).split('|')
+        http_verbs.each { |verb| path[verb] = api }
       end
 
       # method could be symbol array, like: %i[ .. ]
       def api_dry action = :all, desc = '', &block
-        @_apis_blocks ||= { }
+        @_api_dry_blocks ||= { }
         if action.is_a? Array
-          action.each { |m| (@_apis_blocks[m.to_sym] ||= [ ]) << block }
+          action.each { |m| (@_api_dry_blocks[m.to_sym] ||= [ ]) << block }
         else
-          (@_apis_blocks[action.to_sym] ||= [ ]) << block
+          (@_api_dry_blocks[action.to_sym] ||= [ ]) << block
         end
       end
 

lib/open_api/dsl/api_info_obj.rb

@@ -42,12 +42,12 @@ def param param_type, name, type, required, schema_hash = { }
         index.present? ? self[:parameters][index] = param_obj : self[:parameters] << param_obj
       end
 
-      # Support this writing: (just like `form '', data: { }`)
+      # For supporting this: (just like `form '', data: { }` usage)
       #   do_query by: {
       #     :search_type => { type: String  },
       #         :export! => { type: Boolean }
       #   }
-      %i[header header! path path! query query! cookie cookie!].each do |param_type|
+      %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 ]
@@ -56,7 +56,8 @@ def param param_type, name, type, required, schema_hash = { }
         end unless param_type.to_s['!']
       end
 
-      def _param_agent name, type, schema_hash = { }
+      def _param_agent name, type = nil, schema_hash = { }
+        (schema_hash = type) and (type = type.delete(:type)) if type.is_a?(Hash) && type.key?(:type)
         param "#{@param_type}".delete('!'), name, type, (@param_type['!'] ? :req : :opt), schema_hash
       end
 
@@ -122,18 +123,10 @@ def order *param_names
       def param_examples exp_by = :all, examples_hash
         _process_objs
         exp_by = self[:parameters].map { |p| p[:name] } if exp_by == :all
-        # TODO: ref obj
-        # exp_in_params = self[:parameters].map { |p| p[:schema][:examples] }.compact
-        # examples_hash.map! do |key, value|
-        #   if value == []
-        #     if key.in?(exp_in_params.map { |e| e.keys }.flatten.uniq)
-        #       # TODO
-        #     end
-        #   end
-        # end
         self[:examples] = ExampleObj.new(examples_hash, exp_by).process
       end
-      alias_method :examples, :param_examples
+
+      alias examples param_examples
 
 
       def _process_objs
@@ -143,7 +136,7 @@ def _process_objs
 
         # Parameters sorting
         self[:parameters].clone.each do |p|
-          self[:parameters][param_order.index(p[:name])] = p
+          self[:parameters][param_order.index(p[:name]) || -1] = p
         end if param_order.present?
 
         self[:responses]&.each do |code, obj|

lib/open_api/dsl/ctrl_info_obj.rb

@@ -20,7 +20,8 @@ def param component_key, param_type, name, type, required, schema_hash = { }
             ParamObj.new(name, param_type, type, required, schema_hash).process
       end
 
-      def _param_agent component_key, name, type, schema_hash = { }
+      def _param_agent component_key, name, type = nil, schema_hash = { }
+        (schema_hash = type) and (type = type.delete(:type)) if type.is_a?(Hash) && type.key?(:type)
         param component_key,
               "#{@param_type}".delete('!'), name, type, (@param_type['!'] ? :req : :opt), schema_hash
       end

lib/open_api/dsl/helpers.rb

@@ -10,27 +10,26 @@ def load_schema(model)
         #   (1) BuilderSupport module: https://github.com/zhandao/zero-rails/blob/master/app/models/concerns/builder_support.rb
         #   (2) config in model: https://github.com/zhandao/zero-rails/tree/master/app/models/good.rb
         #   (3) jbuilder file: https://github.com/zhandao/zero-rails/blob/mster/app/views/api/v1/goods/index.json.jbuilder
-        # in a word, BuilderSupport let you control the `output fields and nested association infos` very easily.
+        # In a word, BuilderSupport let you control the `output fields and nested association infos` very easily.
         if model.respond_to? :show_attrs
           columns = model.column_names.map(&:to_sym)
           model.show_attrs.map do |attr|
-            if columns.include? attr
-              index = columns.index attr
+            if columns.include?(attr)
+              index = columns.index(attr)
               type = model.columns[index].sql_type_metadata.type.to_s.camelize
               type = 'DateTime' if type == 'Datetime'
               { attr => Object.const_get(type) }
-            elsif attr.match? /_info/
+            elsif attr.match?(/_info/)
               # TODO: 如何获知关系是 many？因为不能只判断结尾是否 ‘s’
               assoc_model = Object.const_get(attr.to_s.split('_').first.singularize.camelize)
               { attr => load_schema(assoc_model) }
             end rescue next
           end
         else
           model.columns.map do |column|
-            name = column.name.to_sym
             type = column.sql_type_metadata.type.to_s.camelize
             type = 'DateTime' if type == 'Datetime'
-            { name => Object.const_get(type) }
+            { column.name.to_sym => Object.const_get(type) }
           end
         end.compact.reduce({ }, :merge) rescue ''
       end
@@ -43,8 +42,8 @@ def load_schema(model)
       #   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
+          _args = (args.size == 1 && args.first.is_a?(Hash)) ? args[0].to_a.flatten : args
+          send(executor, *_args)
         end
       end
 

lib/open_api/generator.rb

@@ -8,7 +8,7 @@ def self.included(base)
 
     module ClassMethods
       def generate_docs(api_name = nil)
-        Dir['./app/controllers/**/*s_controller.rb'].each do |file|
+        Dir['./app/controllers/**/*_controller.rb'].each do |file|
           # Do Not `require`!
           #   It causes problems, such as making `skip_before_action` not working.
           file.sub('./app/controllers/', '').sub('.rb', '').camelize.constantize
@@ -56,7 +56,7 @@ def write_docs(generate_files: true)
         max_length = docs.keys.map(&:size).sort.last
         puts '[ZRO] * * * * * *'
         docs.each do |doc_name, doc|
-          puts "[ZRO] `%#{max_length}s.json` has been generated." % "#{doc_name}"
+          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
         # pp OpenApi.docs
@@ -92,15 +92,17 @@ def self.routes_list
         end
 
       @routes_list ||= routes.split("\n").drop(1).map do |line|
-        infos = line.match(/[A-Z].*/).to_s.split(' ') # => [GET, /api/v1/examples/:id, api/v1/examples#index]
+        next unless line.match?('#')
+        infos = line.match(/[A-Z|].*/).to_s.split(' ') # => [GET, /api/v1/examples/:id, api/v1/examples#index]
+
         {
-            http_verb: infos[0].downcase, # => "get"
+            http_verb: infos[0].downcase, # => "get" / "get|post"
             path: infos[1][0..-11].split('/').map do |item|
                     item[':'] ? "{#{item[1..-1]}}" : item
                   end.join('/'),          # => "/api/v1/examples/{id}"
             action_path: infos[2]         # => "api/v1/examples#index"
         } rescue next
-      end.compact.group_by {|api| api[:action_path].split('#').first } # => { "api/v1/examples" => [..] }, group by paths
+      end.compact.group_by { |api| api[:action_path].split('#').first } # => { "api/v1/examples" => [..] }, group by paths
     end
 
     def self.get_actions_by_ctrl_path(ctrl_path)
@@ -112,7 +114,7 @@ def self.get_actions_by_ctrl_path(ctrl_path)
     def self.find_path_httpverb_by(ctrl_path, action)
       routes_list[ctrl_path]&.map do |action_info|
         if action_info[:action_path].split('#').last == action.to_s
-          return [ action_info[:path], action_info[:http_verb] ]
+          return [ action_info[:path], action_info[:http_verb].split('|').first ]
         end
       end
       nil