zero-rails_openapi 1.7.0 → 2.0.0

data/documentation/examples/goods_doc.rb

@@ -1,52 +0,0 @@
-class V2::GoodsDoc < ApiDoc
-  SCHEMA_DRY = { a: 1, b: 2 }
-
-  #                                 skip: [ 'Token' ] do # you can also skip parameters
-  api :index, 'GET list of goods.', use: [ 'Token', :page, :rows ] do # use parameters write in AutoGenDoc#api_dry
-    desc 'listing goods',
-         view!: 'search view, allows:<br/>',
-         search_type!: 'search field, allows:<br/>'
-
-    # Single `query`
-    query :view, String, enum!: {
-        'all goods (default)': :all,
-                'only online': :online,
-               'only offline': :offline,
-            'expensive goods': :expensive,
-                'cheap goods': :cheap,
-    }, **SCHEMA_DRY # >>> Here is a little trick! <<<
-    # Batch `query`
-    do_query by: {
-        :search_type => { type: String, enum: %w[ name creator category price ] },
-              :value => String,
-             :export => { type: Boolean, desc: 'export as Excel format', examples: {
-                 :right_input => true,
-                 :wrong_input => 'wrong input'
-             }}
-    }
-  end
-
-
-  api :create, 'POST create a good', use: 'Token' do
-    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 } },
-        # -- optional
-           :is_online => { type: Boolean, desc: 'it\'s online?' },
-             :remarks => { type: String,  desc: 'remarks' },
-            :pic_path => { type: String,  desc: 'picture url', is: :url },
-    },
-          exp_by:    %i[ name category_id price ],
-          examples: {
-              :right_input => [ 'good1', 6, 5.7 ],
-              :wrong_input => [ 'good2', 0, -1  ]
-          }
-  end
-
-
-  api :show, 'GET the specified Good.', use: [ 'Token', :id ]
-
-
-  api :destroy, 'DELETE the specified Good.', use: [ 'Token', :id ]
-end

data/documentation/parameter.md

@@ -1,69 +0,0 @@
-### More Explanation for `param` and `schema_info`
-
-#### param_type (param_location)
-OpenAPI 3.0 distinguishes between the following parameter types based on the parameter location: 
-**header, path, query, cookie**. [more](https://swagger.io/docs/specification/describing-parameters/)
-
-#### name (param_name)
-The name of parameter. It can be Symbol or String.
-
-If param_type is :path, it must correspond to the associated path segment form 
-the routing path, for example: if the API path is `/good/:id`, you have to declare a path parameter with name `id` to it.
-
-#### type (schema_type)
-Parameter's (schema) type. We call it `schema_type` because it is inside SchemaObj.
-
-Support all [data types](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#dataTypes) defined in OAS.   
-
-In addition, you can use `format` in schema_info to define in fine detail the data type being used, like: 
-int32, float, date ...  
-All the types you can use as following:
-  - **String, 'binary', 'base64'**
-  - **Integer, Long, 'int32', 'int64', Float, Double**
-  - **File** (it will be converted to `{ type: 'string', format: Config.file_format }`)
-  - **Date, DateTime**
-  - **Boolean**
-  - **Array**: `Array[String]` or `[String]`
-  - Nested Array: `[[[Integer]]]`
-  - **Object**: you can use just `Object`, or use a hash to declare its properties `{ id!: Integer, name: String }` 
-  (`!` bang key means it is required).
-  - Nested Object: `{ id!: Integer, name: { first: String, last: String } }`
-  - Nested Array and Object: `[[{ id!: Integer, name: { first: String, last: String } }]]`
-  - **:ComponentKey**: pass **Symbol** value to type will generate a Schema Reference Object link 
-  to the component correspond to ComponentKey, like: :IdPath, :NameQuery
-  
-  You can use `Object.const_set()` to define a constant that does not exist, but note that 
-  the value you set could not be a Symbol (it will be explained as a Ref Object), should be a String.
-
-#### required
- :opt or :req
-
-#### Schema Hash
-
-The [[schema]](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#schemaObject) defining the type used for the parameter. 
-schema_info(optional) will be used to generate Schema Object inside Parameter Object.  
-[source code](https://github.com/zhandao/zero-rails_openapi/blob/master/lib/oas_objs/schema_obj.rb)  
-You can set the schema by following keys (all are optional), the words in parentheses are available aliases of the keys:  
-  - **enum (values, allowable_values)**  
-  Must be Array or Range(will be converted to Array)
-  - **must_be (value, allowable_value)**  
-  Single value, could be a String, Array ...  
-  - **range (number_range)**  
-  Allow value in this continuous range. Set this field like this: `{ gt: 0, le: 5 }`
-  - **length (lth)**  
-  Must be an Integer, Integer Array, Integer Range, or the following format Symbol: `:gt_`, `:ge_`, `:lt_`, `:le_`, examples: :ge_5 means "greater than or equal 5"; :lt_9 means "lower than 9".
-  - **format (fmt)**
-  - **is (is_a)**  
-    1. It's not in OAS, just an addition field for better express.You can see it as `format`, but in fact they are quite different.  
-    2. Look at this example: the `format` is set to "int32", but you also want to express that this 
-    schema is an "id" format —— this cannot be expressed in the current OAS version.  
-    3. So I suggest that the value of `format` should related to data type, `is` should be an entity.  
-    4. ZRO defaults to identify whether `is` patterns matched the name, then automatically generate `is`. 
-    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)**  
-  Regexp or Time Format
-  - **default (dft, default_value)**
-  - **as** # TODO
-  - **example & examples** # TODO

data/lib/open_api/dsl/common_dsl.rb

@@ -1,39 +0,0 @@
-require 'oas_objs/schema_obj'
-require 'oas_objs/combined_schema'
-require 'oas_objs/param_obj'
-require 'oas_objs/response_obj'
-require 'oas_objs/request_body_obj'
-require 'oas_objs/ref_obj'
-require 'oas_objs/example_obj'
-require 'oas_objs/callback_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|
-          @necessity = param_type['!'] ? :req : :opt
-          @param_type = param_type.to_s.delete('!') # OR: caller[0][/`.*'/][1..-2].to_sym
-          _param_agent *args
-        end
-      end
-
-      %i[ body body! ].each do |method|
-        define_method method do |*args|
-          @necessity = method['!'] ? :req : :opt
-          _request_body_agent *args
-        end
-      end
-
-      # `code`: when defining components, `code` means `component_key`
-      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(desc, media_type, { data: type || data })
-      end
-
-      alias_method :resp,  :response
-      alias_method :error, :response
-    end
-  end
-end

data/lib/open_api/generator.rb

@@ -1,116 +0,0 @@
-require 'open_api/config'
-require 'colorize'
-
-module OpenApi
-  module Generator
-    module_function
-
-    def self.included(base)
-      base.extend ClassMethods
-    end
-
-    module ClassMethods
-      def generate_docs(doc_name = nil)
-        return puts '    ZRO'.red + ' No documents have been configured!' if Config.docs.keys.blank?
-
-        # TODO
-        # :nocov:
-        Dir['./app/controllers/**/*_controller.rb'].each do |file|
-          file.sub('./app/controllers/', '').sub('.rb', '').camelize.constantize
-        end
-        # :nocov:
-        Dir[*Array(Config.doc_location)].each { |file| require file }
-        (doc_name || Config.docs.keys).map { |name| { name => generate_doc(name) } }.reduce({ }, :merge!)
-      end
-
-      def generate_doc(doc_name)
-        settings = Config.docs[doc_name]
-        doc = { openapi: '3.0.0', **settings.slice(:info, :servers) }.merge!(
-                security: settings[:global_security], tags: [ ], paths: { },
-                components: {
-                    securitySchemes: settings[:securitySchemes] || { },
-                    schemas: { }, parameters: { }, requestBodies: { }
-                }
-              )
-
-        [*(bdc = settings[:base_doc_classes]), *bdc.flat_map(&:descendants)].each do |ctrl|
-          doc_info = ctrl.instance_variable_get('@doc_info')
-          next if doc_info.nil?
-
-          doc[:paths].merge!(ctrl.instance_variable_get('@api_info') || { })
-          doc[:tags] << doc_info[:tag]
-          doc[:components].deep_merge!(doc_info[:components] || { })
-          OpenApi.routes_index[ctrl.instance_variable_get('@route_base')] = doc_name
-        end
-
-        doc[:components].delete_if { |_, v| v.blank? }
-        doc[:tags]  = doc[:tags].sort { |a, b| a[:name] <=> b[:name] }
-        doc[:paths] = doc[:paths].sort.to_h
-
-        OpenApi.docs[doc_name] = doc#.delete_if { |_, v| v.blank? }
-      end
-
-      def write_docs(generate_files: true)
-        docs = generate_docs
-        puts '    ZRO loaded.'.green if ENV['RAILS_ENV']
-        return unless generate_files
-        # :nocov:
-        output_path = Config.file_output_path
-        FileUtils.mkdir_p output_path
-        max_length = docs.keys.map(&:size).sort.last
-        docs.each do |doc_name, doc|
-          puts '    ZRO'.green + " `#{doc_name.to_s.rjust(max_length)}.json` has been generated."
-          File.open("#{output_path}/#{doc_name}.json", 'w') { |file| file.write JSON.pretty_generate doc }
-        end
-        # :nocov:
-      end
-    end
-    # end of module
-
-    def routes
-      @routes ||=
-          if (file = Config.rails_routes_file)
-            File.read(file)
-          else
-            # :nocov:
-            # ref https://github.com/rails/rails/blob/master/railties/lib/rails/tasks/routes.rake
-            require './config/routes'
-            all_routes = Rails.application.routes.routes
-            require 'action_dispatch/routing/inspector'
-            inspector = ActionDispatch::Routing::RoutesInspector.new(all_routes)
-            inspector.format(ActionDispatch::Routing::ConsoleFormatter.new, nil)
-            # :nocov:
-          end
-    end
-
-    def routes_list
-      @routes_list ||= routes.split("\n").drop(1).map do |line|
-        next unless line['#']
-        infos = line.match(/[A-Z|].*/).to_s.split(' ') # => [GET, /api/v1/examples/:id, api/v1/examples#index]
-
-        {
-            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
-
-    def get_actions_by_route_base(route_base)
-      routes_list[route_base]&.map do |action_info|
-        action_info[:action_path].split('#').last
-      end
-    end
-
-    def find_path_httpverb_by(route_base, action)
-      routes_list[route_base]&.map do |action_info|
-        if action_info[:action_path].split('#').last == action.to_s
-          return [ action_info[:path], action_info[:http_verb].split('|').first ]
-        end
-      end
-      nil
-    end
-  end
-end