oas_rails 0.11.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c02c7a454cec38660f5d327e61f35c88e3d7ab22b4fc5c18adbed3707c656d7
-  data.tar.gz: 8fb227b665f88c0c6299f1a1bbd9d4c681f1438c13fa93e6f552cd96b1ef7a00
+  metadata.gz: d0b32fa577fb8e747811369e952c3508011a6270366784ab3eb0ff69d579c51b
+  data.tar.gz: 251e05d5a07104a8cea8635197dbf110d0749576f383aa38de6ebe7cebf89c06
 SHA512:
-  metadata.gz: 2d30c6f893f17476716208e57311b2c290f99208431781085de77d97d9c6c2d5601df5c29e53155d485a3e2d1268383ca6151dd97ae629461db2b8c369df9cdc
-  data.tar.gz: 6b7edd8df46e2ea3b8c20fdbc41ceed453f560a0c619fed3138ae49a5366625e34b36fd0ee6c5d1aff549602c00ae2e4e1b880b58ae1e6f62ffed4c1578e4c6d
+  metadata.gz: 9bcb332e43ce4caa1be24e598589a9fdba1dad280488d9c3a6b3764b0037bba2b484c525f5733bfd26fa77b76ee3f9944c88c6d6fbe3dc6649c33203d1cf9d47
+  data.tar.gz: 4153c860f49b50c870e3ee86382b08fa29686e96aef9f2e39056b4d4f6364617963e6d71a1e48e3bdee25ef7149548c5974986c7884c5ab6be235b642d13a8c0

data/README.md

@@ -39,7 +39,7 @@ The goal is to minimize the effort required to create comprehensive documentatio
 
 ## Documentation
 
-For see how to install, configure and use OasRails please refere to the [OasRailsBook](http://a-chacon.com/oas_rails/book)
+For see how to install, configure and use OasRails please refere to the [OasRailsBook](http://a-chacon.com/oas_rails)
 
 ## Contributing
 

data/app/views/oas_rails/oas_rails/index.html.erb

@@ -133,6 +133,7 @@
       nav-item-spacing="relaxed"
       allow-spec-file-download="true"
       schema-style="table"
+      sort-tags="true"
     >
     </rapi-doc>
 

data/lib/generators/oas_rails/config/templates/oas_rails_initializer.rb

@@ -26,6 +26,8 @@ OasRails.configure do |config|
 
     3. Use Yard tags in your controller methods to provide detailed API endpoint descriptions.
 
+    Docs: <https://a-chacon.com/oas_rails/>
+
     ## Features
 
     - Automatic OAS 3.1 document generation
@@ -105,6 +107,7 @@ OasRails.configure do |config|
   # Example, if you add forbidden then it will be added only if the endpoint requires authentication.
   # Example: not_found will be setted to the endpoint only if the operation is a show/update/destroy action.
   # config.set_default_responses = true
-  # config.possible_default_responses = [:not_found, :unauthorized, :forbidden]
-  # config.response_body_of_default = { message: String }
+  # config.possible_default_responses = [:not_found, :unauthorized, :forbidden, :internal_server_error, :unprocessable_entity]
+  # config.response_body_of_default = "Hash{ message: String }"
+  # config.response_body_of_unprocessable_entity= "Hash{ errors: Array<String> }"
 end

data/lib/oas_rails/builders/content_builder.rb

@@ -33,7 +33,7 @@ module OasRails
       end
 
       def from_model_class(klass)
-        return self unless klass.ancestors.map(&:to_s).include? 'ActiveRecord::Base'
+        return self unless Utils.active_record_class?(klass)
 
         model_schema = Builders::EsquemaBuilder.send("build_#{@context}_schema", klass:)
         model_schema["required"] = []

data/lib/oas_rails/builders/request_body_builder.rb

@@ -18,7 +18,7 @@ module OasRails
       end
 
       def from_tags(tag:, examples_tags: [])
-        if tag.klass.ancestors.map(&:to_s).include? 'ActiveRecord::Base'
+        if Utils.active_record_class?(tag.klass)
           from_model_class(klass: tag.klass, description: tag.text, required: tag.required, examples_tags:)
         else
           @request_body.description = tag.text

data/lib/oas_rails/builders/responses_builder.rb

@@ -32,29 +32,49 @@ module OasRails
       def add_default_responses(oas_route, security)
         return self unless OasRails.config.set_default_responses
 
-        content = ContentBuilder.new(@specification, :outgoing).with_schema(JsonSchemaGenerator.process_string(OasRails.config.response_body_of_default)[:json_schema]).build
+        common_errors = determine_common_errors(oas_route, security)
+        add_responses_for_errors(common_errors)
+
+        self
+      end
+
+      def build
+        @responses
+      end
+
+      private
+
+      def determine_common_errors(oas_route, security)
         common_errors = []
-        common_errors.push(:unauthorized, :forbidden) if security
+        common_errors.push(:unauthorized, :forbidden, :internal_server_error) if security
 
         case oas_route.method
-        when "show", "update", "destroy"
+        when "show", "destroy"
           common_errors.push(:not_found)
-        when "create", "index"
-          # possible errors for this methods?
+        when "create"
+          common_errors.push(:unprocessable_entity)
+        when "update"
+          common_errors.push(:not_found, :unprocessable_entity)
         end
 
-        (OasRails.config.possible_default_responses & common_errors).each do |e|
-          code = Utils.status_to_integer(e)
+        OasRails.config.possible_default_responses & common_errors
+      end
+
+      def add_responses_for_errors(errors)
+        errors.each do |error|
+          response_body = resolve_response_body(error)
+          content = ContentBuilder.new(@specification, :outgoing).with_schema(JsonSchemaGenerator.process_string(response_body)[:json_schema]).build
+          code = Utils.status_to_integer(error)
           response = ResponseBuilder.new(@specification).with_code(code).with_description(Utils.get_definition(code)).with_content(content).build
 
           @responses.add_response(response) if @responses.responses[response.code].blank?
         end
-
-        self
       end
 
-      def build
-        @responses
+      def resolve_response_body(error)
+        OasRails.config.public_send("response_body_of_#{error}")
+      rescue StandardError
+        OasRails.config.response_body_of_default
       end
     end
   end

data/lib/oas_rails/configuration.rb

@@ -11,11 +11,11 @@ module OasRails
                   :authenticate_all_routes_by_default,
                   :set_default_responses,
                   :possible_default_responses,
-                  :response_body_of_default,
                   :http_verbs,
                   :use_model_names,
                   :rapidoc_theme
-    attr_reader :servers, :tags, :security_schema
+
+    attr_reader :servers, :tags, :security_schema, :include_mode, :response_body_of_default
 
     def initialize
       @info = Spec::Info.new
@@ -32,11 +32,28 @@ module OasRails
       @security_schema = nil
       @security_schemas = {}
       @set_default_responses = true
-      @possible_default_responses = [:not_found, :unauthorized, :forbidden]
+      @possible_default_responses = [:not_found, :unauthorized, :forbidden, :internal_server_error, :unprocessable_entity]
       @http_verbs = [:get, :post, :put, :patch, :delete]
-      @response_body_of_default = "Hash{ success: !Boolean, message: String }"
+      @response_body_of_default = "Hash{ status: !Integer, error: String }"
       @use_model_names = false
       @rapidoc_theme = :rails
+      @include_mode = :all
+
+      @possible_default_responses.each do |response|
+        method_name = "response_body_of_#{response}="
+        variable_name = "@response_body_of_#{response}"
+
+        define_singleton_method(method_name) do |value|
+          raise ArgumentError, "#{method_name} must be a String With a valid object" unless value.is_a?(String)
+
+          OasRails::JsonSchemaGenerator.parse_type(value)
+          instance_variable_set(variable_name, value)
+        end
+
+        define_singleton_method("response_body_of_#{response}") do
+          instance_variable_get(variable_name) || @response_body_of_default
+        end
+      end
     end
 
     def security_schema=(value)
@@ -64,6 +81,20 @@ module OasRails
     def excluded_columns_outgoing
       []
     end
+
+    def include_mode=(value)
+      valid_modes = [:all, :with_tags, :explicit]
+      raise ArgumentError, "include_mode must be one of #{valid_modes}" unless valid_modes.include?(value)
+
+      @include_mode = value
+    end
+
+    def response_body_of_default=(value)
+      raise ArgumentError, "response_body_of_default must be a String With a valid object" unless value.is_a?(String)
+
+      OasRails::JsonSchemaGenerator.parse_type(value)
+      @response_body_of_default = value
+    end
   end
 
   DEFAULT_SECURITY_SCHEMES = {

data/lib/oas_rails/extractors/render_response_extractor.rb

@@ -60,7 +60,7 @@ module OasRails
           maybe_a_model, errors = content.gsub('@', "").split(".")
           klass = maybe_a_model.singularize.camelize(:upper).constantize
 
-          if klass.ancestors.map(&:to_s).include? 'ActiveRecord::Base'
+          if Utils.active_record_class?(klass)
             schema = Builders::EsquemaBuilder.build_outgoing_schema(klass:)
             if test_singularity(maybe_a_model)
               build_singular_model_schema_and_examples(maybe_a_model, errors, klass, schema)

data/lib/oas_rails/extractors/route_extractor.rb

@@ -45,41 +45,14 @@ module OasRails
           route.gsub('(.:format)', '').gsub(/:\w+/) { |match| "{#{match[1..]}}" }
         end
 
-        # THIS CODE IS NOT IN USE BUT CAN BE USEFULL WITH GLOBAL TAGS OR AUTH TAGS
-        # def get_controller_comments(controller_path)
-        #   YARD.parse_string(File.read(controller_path))
-        #   controller_class = YARD::Registry.all(:class).first
-        #   if controller_class
-        #     class_comment = controller_class.docstring.all
-        #     method_comments = controller_class.meths.map do |method|
-        #       {
-        #         name: method.name,
-        #         comment: method.docstring.all
-        #       }
-        #     end
-        #     YARD::Registry.clear
-        #     {
-        #       class_comment: class_comment,
-        #       method_comments: method_comments
-        #     }
-        #   else
-        #     YARD::Registry.clear
-        #     nil
-        #   end
-        # rescue StandardError
-        #   nil
-        # end
-        #
-        # def get_controller_comment(controller_path)
-        #   get_controller_comments(controller_path)&.dig(:class_comment) || ''
-        # rescue StandardError
-        #   ''
-        # end
-
         private
 
         def extract_host_routes
-          valid_routes.map { |r| OasRoute.new_from_rails_route(rails_route: r) }
+          routes = valid_routes.map { |r| OasRoute.new_from_rails_route(rails_route: r) }
+
+          routes.select! { |route| route.docstring.tags.any? } if OasRails.config.include_mode == :with_tags
+          routes.select! { |route| route.docstring.tags.any? { |t| t.tag_name == "oas_include" } } if OasRails.config.include_mode == :explicit
+          routes
         end
 
         def valid_routes

data/lib/oas_rails/json_schema_generator.rb

@@ -29,6 +29,8 @@ module OasRails
         { type: :object, required:, properties: parse_object_properties(::Regexp.last_match(1)) }
       when /^Array<(.+)>$/i
         { type: :array, required:, items: parse_type(::Regexp.last_match(1)) }
+      when ->(t) { Utils.active_record_class?(t) }
+        Builders::EsquemaBuilder.build_outgoing_schema(klass: type.constantize)
       else
         { type: type.downcase.to_sym, required: }
       end
@@ -100,6 +102,8 @@ module OasRails
           type: 'array',
           items: to_json_schema(parsed[:items])
         }
+      when nil
+        parsed
       else
         ruby_type_to_json_schema_type(parsed[:type])
       end

data/lib/oas_rails/utils.rb

@@ -14,6 +14,8 @@ module OasRails
     }.freeze
 
     HTTP_STATUS_DEFINITIONS = {
+      200 => "The request has succeeded.",
+      201 => "The request has been fulfilled and resulted in a new resource being created.",
       404 => "The requested resource could not be found.",
       401 => "You are not authorized to access this resource. You need to authenticate yourself first.",
       403 => "You are not allowed to access this resource. You do not have the necessary permissions.",
@@ -34,19 +36,6 @@ module OasRails
         end
       end
 
-      # TODO: check if it is in use
-      def type_to_schema(type_string)
-        if type_string.start_with?('Array<')
-          inner_type = type_string[/Array<(.+)>$/, 1]
-          {
-            "type" => "array",
-            "items" => type_to_schema(inner_type)
-          }
-        else
-          { "type" => TYPE_MAPPING.fetch(type_string, 'string') }
-        end
-      end
-
       def hash_to_json_schema(hash)
         {
           type: 'object',
@@ -116,6 +105,16 @@ module OasRails
 
         nil # Return nil if no matching constant is found
       end
+
+      # Checks if a given text refers to an ActiveRecord class.
+      # @param text [String] The text to check.
+      # @return [Boolean] True if the text refers to an ActiveRecord class, false otherwise.
+      def active_record_class?(klass_or_string)
+        klass = klass_or_string.is_a?(Class) ? klass_or_string : klass_or_string.constantize
+        klass.ancestors.map(&:to_s).include? 'ActiveRecord::Base'
+      rescue StandardError
+        false
+      end
     end
   end
 end

data/lib/oas_rails/version.rb

@@ -1,3 +1,3 @@
 module OasRails
-  VERSION = "0.11.0"
+  VERSION = "0.13.0"
 end

data/lib/oas_rails/yard/oas_rails_factory.rb

@@ -147,23 +147,13 @@ module OasRails
         match
       end
 
-      # Checks if a given text refers to an ActiveRecord class.
-      # @param text [String] The text to check.
-      # @return [Boolean] True if the text refers to an ActiveRecord class, false otherwise.
-      def active_record_class?(text)
-        klass = text.constantize
-        klass.ancestors.map(&:to_s).include? 'ActiveRecord::Base'
-      rescue StandardError
-        false
-      end
-
       # Converts type text to a schema, checking if it's an ActiveRecord class.
       # @param text [String] The type text to convert.
       # @return [Array] An array containing the class, schema, and required flag.
       def type_text_to_schema(text)
         type_text, required = text_and_required(text)
 
-        if active_record_class?(type_text)
+        if Utils.active_record_class?(type_text)
           klass = type_text.constantize
           schema = Builders::EsquemaBuilder.build_outgoing_schema(klass:)
         else

data/lib/oas_rails.rb

@@ -90,7 +90,8 @@ module OasRails
         'Endpoint Tags' => [:tags],
         'Summary' => [:summary],
         'No Auth' => [:no_auth],
-        'Auth methods' => [:auth, :with_types]
+        'Auth methods' => [:auth, :with_types],
+        'OAS Include' => [:oas_include]
       }
       yard_tags.each do |tag_name, (method_name, handler)|
         ::YARD::Tags::Library.define_tag(tag_name, method_name, handler)

metadata

@@ -1,29 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: oas_rails
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.13.0
 platform: ruby
 authors:
 - a-chacon
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-04-07 00:00:00.000000000 Z
+date: 2025-04-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: easy_talk
+  name: easy_talk_two
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: 1.1.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: 1.1.2
 - !ruby/object:Gem::Dependency
   name: method_source
   requirement: !ruby/object:Gem::Requirement