zero-rails_openapi 1.7.0 → 2.0.0

data/lib/oas_objs/schema_obj_helpers.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module OpenApi
   module DSL
     module SchemaObjHelpers
@@ -7,11 +9,11 @@ module OpenApi
         #     id!: { type: Integer, enum: 0..5, desc: 'user id' }
         # }, should have description within schema
         if t.key?(:type)
-          SchemaObj.new(t[:type], t).process(inside_desc: true)
+          SchemaObj.new(t[:type], t).process
 
           # For supporting combined schema in nested schema.
         elsif (t.keys & %i[ one_of any_of all_of not ]).present?
-          CombinedSchema.new(t).process(inside_desc: true)
+          CombinedSchema.new(t).process
         else
           obj_type(t)
         end
@@ -22,59 +24,33 @@ module OpenApi
 
         t.each do |prop_name, 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)
+          obj_type[:properties][prop_name.to_s.delete('!').to_sym] = recg_schema_type(prop_type)
         end
         obj_type.keep_if &value_present
       end
 
       def array_type(t)
-        t = t.size == 1 ? t.first : { one_of: t }
         {
             type: 'array',
-            items: processed_type(t)
+            items: recg_schema_type(t.one? ? t[0] : { one_of: t })
         }
       end
 
-      def process_range_enum_and_lth
-        self[:_enum] = str_range_to_a(_enum) if _enum.is_a?(Range)
-        self[:_length] = str_range_to_a(_length) if _length.is_a?(Range)
-
-        values = _enum || _value
-        self._enum = Array(values) if truly_present?(values)
-      end
-
       def str_range_to_a(val)
         val_class = val.first.class
         action = :"to_#{val_class.to_s.downcase[0]}"
         (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_desc': :all,
-        #     'one_desc': :one
-        # }
-        self._enum ||= (e = self[:enum!])
-        return unless e.is_a? Hash
-        @enum_info = e
-        self._enum = e.values
-      end
-
-      # TODO: more info and desc configure
       def auto_generate_desc
-        return __desc if _enum.blank?
-
-        if @enum_info.present?
-          @enum_info.each_with_index do |(info, value), index|
-            __desc.concat "<br/>#{index + 1}/ #{info}: #{value}"
+        if @bang_enum.is_a?(Hash)
+          @bang_enum.each_with_index do |(info, value), index|
+            self._desc = _desc + "<br/>#{index + 1}/ #{info}: #{value}"
           end
         else
-          _enum.each_with_index do |value, index|
-            __desc.concat "<br/>#{index + 1}/ #{value}"
-          end
+          @bang_enum.each_with_index { |value, index| self._desc = _desc + "<br/>#{index + 1}/ #{value}" }
         end
-        __desc
+        _desc
       end
     end
   end

data/lib/open_api.rb

@@ -1,16 +1,67 @@
+# frozen_string_literal: true
+
+require 'colorize'
+
 require 'open_api/version'
+require 'open_api/support/tip'
 require 'open_api/config'
-require 'open_api/generator'
+require 'open_api/router'
 require 'open_api/dsl'
 
 module OpenApi
-  include Generator
+  module_function
+  cattr_accessor :routes_index, default: { }
+  cattr_accessor :docs, default: { }
+
+  def write_docs(if: true, read_on_controller: true)
+    (docs = generate_docs(read_on_controller)) and Tip.loaded
+    return unless binding.local_variable_get :if
+
+    FileUtils.mkdir_p Config.file_output_path
+    docs.each do |name, doc|
+      File.write "#{Config.file_output_path}/#{name}.json", JSON.pretty_generate(doc)
+      Tip.generated(name.to_s.rjust(docs.keys.map(&:size).max))
+    end
+  end
+
+  def generate_docs(read_on_controller)
+    return Tip.no_config if Config.docs.keys.blank?
+    traverse_controllers if read_on_controller
+    Dir[*Array(Config.doc_location)].each { |file| require file }
+    Config.docs.keys.map { |name| [ name, generate_doc(name) ] }.to_h
+  end
+
+  def generate_doc(doc_name)
+    settings, doc = init_hash(doc_name)
+    [*(bdc = settings[:base_doc_classes]), *bdc.flat_map(&:descendants)].each do |kls|
+      next if kls.oas[:doc].blank?
+      doc[:paths].merge!(kls.oas[:apis])
+      doc[:tags] << kls.oas[:doc][:tag]
+      doc[:components].deep_merge!(kls.oas[:doc][:components] || { })
+      OpenApi.routes_index[kls.oas[: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
 
-  cattr_accessor :routes_index do
-    { }
+  def init_hash(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: { }
+        }
+    )
+    [ settings, doc ]
   end
 
-  cattr_accessor :docs do
-    { }
+  def traverse_controllers
+    Dir['./app/controllers/**/*_controller.rb'].each do |file|
+      file.sub('./app/controllers/', '').sub('.rb', '').camelize.constantize
+    end
   end
 end

data/lib/open_api/config.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'open_api/config_dsl'
 require 'active_support/all'
 
@@ -5,51 +7,22 @@ module OpenApi
   module Config
     include ConfigDSL
 
-    # [REQUIRED] The location where .json doc file will be output.
-    cattr_accessor :file_output_path do
-      'public/open_api'
-    end
+    cattr_accessor :default_run_dry, default: false
 
-    cattr_accessor :generate_doc do
-      true
-    end
+    # [REQUIRED] The location where .json doc file will be output.
+    cattr_accessor :file_output_path, default: 'public/open_api'
 
-    cattr_accessor :doc_location do
-      ['./app/**/*_doc.rb']
-    end
+    cattr_accessor :doc_location, default: ['./app/**/*_doc.rb']
 
-    cattr_accessor :rails_routes_file do
-      nil
-    end
+    cattr_accessor :rails_routes_file
 
-    cattr_accessor :active_record_base do
-      nil
-    end
+    cattr_accessor :model_base
 
     # Everything about OAS3 is on https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md
     # Getting started: https://swagger.io/docs/specification/basic-structure/
-    cattr_accessor :open_api_docs do
-      {
-      #     # [REQUIRED] At least one doc.
-      #     zero_rails: {
-      #         # [REQUIRED] ZRO will scan all the descendants of the base_doc_classes, and then generate their docs.
-      #         base_doc_classes: [ApplicationController],
-      #
-      #         # [REQUIRED] Info Object: The info section contains API information
-      #         info: {
-      #             # [REQUIRED] The title of the application.
-      #             title: 'Zero Rails Apis',
-      #             # [REQUIRED] The version of the OpenAPI document
-      #             # (which is distinct from the OpenAPI Specification version or the API implementation version).
-      #             version: '0.0.1'
-      #         }
-      #     }
-      }
-    end
+    cattr_accessor :open_api_docs, default: { }
 
-    cattr_accessor :file_format do
-      'binary'
-    end
+    cattr_accessor :file_format, default: 'binary'
 
     def self.docs
       open_api_docs

data/lib/open_api/config_dsl.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module OpenApi
   module ConfigDSL
     def self.included(base)

data/lib/open_api/dsl.rb

@@ -1,73 +1,60 @@
+# frozen_string_literal: true
+
 require 'open_api/dsl/api'
 require 'open_api/dsl/components'
-require 'colorize'
 
 module OpenApi
   module DSL
-    def self.included(base)
-      base.extend ClassMethods
-    end
+    extend ActiveSupport::Concern
+    
+    class_methods do
+      def oas
+        @oas ||= { doc: { }, dry_blocks: { }, apis: { }, route_base: try(:controller_path),
+                   tag_name: try(:controller_name)&.camelize }
+      end
 
-    # TODO: Doc-Block Comments
-    module ClassMethods
       def route_base path
-        @route_base = path
-        @doc_tag    = path.split('/').last.camelize
+        oas[:route_base] = path
+        oas[:tag_name] = path.split('/').last.camelize
       end
 
-      def doc_tag name: nil, desc: '', external_doc_url: nil
-        # apis will group by the tags.
-        @doc_tag = name if name.present?
-        @doc_tag ||= controller_name.camelize
-        tag = (@doc_info = { })[:tag] = { name: @doc_tag }
-        tag[:description]  = desc if desc.present?
-        tag[:externalDocs] = { description: 'ref', url: external_doc_url } if external_doc_url
+      # APIs will be grouped by tags.
+      def doc_tag name: nil, **tag_info #  description: ..., externalDocs: ...
+        oas[:doc][:tag] = { name: name || oas[:tag_name], **tag_info }
       end
 
       def components &block
-        doc_tag if @doc_info.nil?
-        structure = %i[ schemas responses	parameters examples requestBodies securitySchemes ].map { |k| [k, { }] }.to_h
-        current_doc = Components.new.merge!(structure)
-        current_doc.instance_exec(&block)
-        current_doc.process_objs
-
-        (@doc_info[:components] ||= { }).deep_merge!(current_doc)
+        doc_tag if oas[:doc].blank?
+        (components = Components.new).instance_exec(&block)
+        components.process_objs
+        (oas[:doc][:components] ||= { }).deep_merge!(components)
       end
 
-      def api action, summary = '', id: nil, tag: nil, http: http_method = nil, skip: [ ], use: [ ], &block
-        doc_tag if @doc_info.nil?
-        # select the routing info (corresponding to the current method) from routing list.
-        action_path = "#{@route_base ||= controller_path}##{action}"
-        routes = ctrl_routes_list&.select { |api| api[:action_path][/^#{action_path}$/].present? }
-        return puts '    ZRO'.red + " Route mapping failed: #{action_path}" if routes.blank?
+      def api action, summary = '', id: nil, tag: nil, http: nil, dry: Config.default_run_dry, &block
+        doc_tag if oas[:doc].blank?
+        action_path = "#{oas[:route_base]}##{action}"
+        routes = Router.routes_list[oas[:route_base]]
+                     &.select { |api| api[:action_path][/^#{action_path}$/].present? }
+        return Tip.no_route(action_path) if routes.blank?
+
+        tag = tag || oas[:doc][:tag][:name]
+        api = Api.new(action_path, summary: summary, tags: [tag], id: id || "#{tag}_#{action.to_s.camelize}")
+        [action, tag, :all].each { |key| api.dry_blocks.concat(oas[:dry_blocks][key] || [ ]) }
+        api.run_dsl(dry: dry, &block)
+        _set_apis(api, routes, http)
+      end
 
-        api = Api.new(action_path, skip: Array(skip), use: Array(use))
-                 .merge! description: '', summary: summary, operationId: id || "#{@doc_info[:tag][:name]}_#{action.to_s.camelize}",
-                         tags: [tag || @doc_tag], parameters: [ ], requestBody: '',  responses: { },  callbacks: { },
-                         links: { }, security: [ ], servers: [ ]
-        [action, :all].each { |blk_key| @zro_dry_blocks&.[](blk_key)&.each { |blk| api.instance_eval(&blk) } }
-        api.param_use = api.param_skip = [ ] # `skip` and `use` only affect `api_dry`'s blocks
-        api.instance_exec(&block) if block_given?
-        api.process_objs
-        api.delete_if { |_, v| v.blank? }
+      def api_dry action_or_tags = :all, &block
+        Array(action_or_tags).each { |a| (oas[:dry_blocks][a.to_sym] ||= [ ]) << block }
+      end
 
+      def _set_apis(api, routes, http)
         routes.each do |route|
-          path = (@api_info ||= { })[route[:path]] ||= { }
+          path = oas[:apis][route[:path]] ||= { }
           (http || route[:http_verb]).split('|').each { |verb| path[verb] = api }
         end
-
         api
       end
-
-      # method could be symbol array, like: %i[ .. ]
-      def api_dry action = :all, desc = '', &block
-        @zro_dry_blocks ||= { }
-        Array(action).each { |a| (@zro_dry_blocks[a.to_sym] ||= [ ]) << block }
-      end
-
-      def ctrl_routes_list
-        Generator.routes_list[@route_base]
-      end
     end
   end
 end

data/lib/open_api/dsl/api.rb

@@ -1,21 +1,22 @@
-require 'open_api/dsl/common_dsl'
+# frozen_string_literal: true
+
+require 'open_api/dsl/helpers'
 
 module OpenApi
   module DSL
     class Api < Hash
-      include DSL::CommonDSL
       include DSL::Helpers
 
-      attr_accessor :action_path, :param_skip, :param_use, :param_descs, :param_order
+      attr_accessor :action_path, :dry_skip, :dry_only, :dry_blocks, :dryed, :param_order
 
-      def initialize(action_path = '', skip: [ ], use: [ ])
+      def initialize(action_path = '', summary: nil, tags: [ ], id: nil)
         self.action_path = action_path
-        self.param_skip  = skip
-        self.param_use   = use
-        self.param_descs = { }
+        self.dry_blocks  = [ ]
+        self.merge!(summary: summary, operationId: id, tags: tags, description: '', parameters: [ ],
+                    requestBody: nil, responses: { }, callbacks: { }, links: { }, security: [ ], servers: [ ])
       end
 
-      def this_api_is_invalid! explain = ''
+      def this_api_is_invalid!(*)
         self[:deprecated] = true
       end
 
@@ -23,41 +24,41 @@ module OpenApi
       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
+      def desc desc
         self[:description] = desc
       end
 
-      def param param_type, name, type, required, schema_info = { }
-        return if param_skip.include?(name)
-        return if param_use.present? && param_use.exclude?(name)
+      alias description desc
 
-        schema_info[:desc]  ||= param_descs[name]
-        schema_info[:desc!] ||= param_descs[:"#{name}!"]
-        param_obj = ParamObj.new(name, param_type, type, required, schema_info)
-        # The definition of the same name parameter will be overwritten
-        fill_in_parameters(param_obj)
+      def dry only: nil, skip: nil, none: false
+        return if dry_blocks.blank? || dryed
+        self.dry_skip = skip && Array(skip)
+        self.dry_only = none ? [:none] : only && Array(only)
+        dry_blocks.each { |blk| instance_eval(&blk) }
+        self.dry_skip = self.dry_only = nil
+        self.dryed = true
       end
 
-      # [ header header! path path! query query! cookie cookie! ]
-      def _param_agent name, type = nil, **schema_info
-        schema = process_schema_info(type, schema_info)
-        return puts '    ZRO'.red + " Syntax Error: param `#{name}` has no schema type!" if schema[:illegal?]
-        param @param_type, name, schema[:type], @necessity, schema[:combined] || schema[:info]
+      def param param_type, name, type, required, schema = { }
+        return if dry_skip&.include?(name) || dry_only&.exclude?(name)
+
+        return unless schema = process_schema_input(type, schema, name)
+        param_obj = ParamObj.new(name, param_type, type, required, schema)
+        # The definition of the same name parameter will be overwritten
+        index = self[:parameters].map(&:name).index(param_obj.name)
+        index ? self[:parameters][index] = param_obj : self[:parameters] << param_obj
       end
 
-      # For supporting this: (just like `form '', data: { }` usage)
-      #   do_query by: {
-      #     :search_type => { type: String  },
-      #         :export! => { type: Boolean }
-      #   }
+      alias parameter param
+
       %i[ header header! path path! query query! cookie cookie! ].each do |param_type|
-        define_method "do_#{param_type}" do |by:, **common_schema|
-          by.each do |param_name, schema|
-            action = "#{param_type}#{param_name['!']}".sub('!!', '!')
-            type, schema = schema.is_a?(Hash) ? [schema[:type], schema] : [schema, { }]
-            args = [ param_name.to_s.delete('!').to_sym, type, schema.reverse_merge!(common_schema) ]
-            send(action, *args)
+        define_method param_type do |name, type = nil, **schema|
+          param param_type, name, type, (param_type['!'] ? :req : :opt), schema
+        end
+
+        define_method "in_#{param_type}" do |params|
+          params.each_pair do |param_name, schema|
+            param param_type, param_name, nil, (param_type['!'] || param_name['!'] ? :req : :opt), schema
           end
         end
       end
@@ -66,22 +67,21 @@ module OpenApi
         self[:parameters] += [component_key, *keys].map { |key| RefObj.new(:parameter, key) }
       end
 
-      # 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, { data: data , **options })
-      end
-
-      # [ body body! ]
-      def _request_body_agent media_type, data: { }, **options
-        request_body @necessity, media_type, data: data, **options
+      # options: `exp_params` and `examples`
+      def request_body required, media_type, data: { }, desc: '', **options
+        (self[:requestBody] ||= RequestBodyObj.new(required, desc)).absorb(media_type, { data: data , **options })
       end
 
       def body_ref component_key
         self[:requestBody] = RefObj.new(:requestBody, component_key)
       end
 
+      %i[ body body! ].each do |method|
+        define_method method do |media_type, data: { }, **options|
+          request_body (method['!'] ? :req : :opt), media_type, data: data, **options
+        end
+      end
+
       def form data:, **options
         body :form, data: data, **options
       end
@@ -90,21 +90,20 @@ module OpenApi
         body! :form, data: data, **options
       end
 
-      def data name, type = nil, schema_info = { }
-        schema_info[:type] = type if type.present?
-        form data: { name => schema_info }
+      def data name, type = nil, schema = { }
+        schema[:type] = type if type.present?
+        form data: { name => schema }
       end
 
-      def file media_type, data: { type: File }, **options
-        body media_type, data: data, **options
+      def response code, desc, media_type = nil, data: { }
+        (self[:responses][code] ||= ResponseObj.new(desc)).absorb(desc, media_type, { data: data })
       end
 
-      def file! media_type, data: { type: File }, **options
-        body! media_type, data: data, **options
-      end
+      alias_method :resp,  :response
+      alias_method :error, :response
 
-      def response_ref code_compkey_hash
-        code_compkey_hash.each { |code, component_key| self[:responses][code] = RefObj.new(:response, component_key) }
+      def response_ref code_and_compkey # = { }
+        code_and_compkey.each { |code, component_key| self[:responses][code] = RefObj.new(:response, component_key) }
       end
 
       def security_require scheme_name, scopes: [ ]
@@ -113,7 +112,7 @@ module OpenApi
 
       alias security  security_require
       alias auth      security_require
-      alias need_auth security_require
+      alias auth_with security_require
 
       def callback event_name, http_method, callback_url, &block
         self[:callbacks].deep_merge! CallbackObj.new(event_name, http_method, callback_url, &block).process
@@ -123,26 +122,22 @@ module OpenApi
         self[:servers] << { url: url, description: desc }
       end
 
-      def order *param_names
-        self.param_order = param_names
-        # be used when `api_dry`
-        self.param_use = param_order if param_use.blank?
-        self.param_skip = param_use - param_order
-      end
-
-      def param_examples exp_by = :all, examples_hash
-        exp_by = self[:parameters].map(&:name) if exp_by == :all
-        self[:examples] = ExampleObj.new(examples_hash, exp_by, multiple: true).process
+      def param_examples exp_params = :all, examples_hash
+        exp_params = self[:parameters].map(&:name) if exp_params == :all
+        self[:examples] = ExampleObj.new(examples_hash, exp_params, multiple: true).process
       end
 
       alias examples param_examples
 
-      def process_objs
-        self[:parameters].map!(&:process)
-        self[:parameters].sort_by! { |param| param_order.index(param[:name]) || Float::INFINITY } if param_order.present?
+      def run_dsl(dry: false, &block)
+        instance_exec(&block) if block_given?
+        dry() if dry
 
+        self[:parameters].map!(&:process)
         self[:requestBody] = self[:requestBody].try(:process)
         self[:responses].each { |code, response| self[:responses][code] = response.process }
+        self[:responses] = self[:responses].sort.to_h
+        self.delete_if { |_, v| v.blank? }
       end
     end
   end