oas_rails 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3f5da00f122856b6cce2f73b5912013477726bda80f57f39fdbe4609bc551c7
-  data.tar.gz: 35def82214e4c8b01755ddb2b501140f45ab653d575512ec52730d5722f7b025
+  metadata.gz: 1f833de18481bb481d9f698a2f10a3b7f1a1512623cd335932659736f94b2161
+  data.tar.gz: 343243f10ae846b8eb42ca75cdd3d69332fe19b41192959bb355603fa2148242
 SHA512:
-  metadata.gz: f6854cfb18a0770b11dae6e87da5a7a5d3521d3967bd27656cf6e69ac3f3dfb8342b045f04af2ba27ab969e1b5615dd757fb26e9632628811741f0876f473a94
-  data.tar.gz: 994dc70c3ba5b1a935686b9f7c90913bd59106d8981db340f788d38d048226f1acef0eb113d2e12534c5eec83d7a5ee8d9fd159da923bbcbd412e8d72a9eb758
+  metadata.gz: 3e41ce594245affa26d85f05bba1fbdb1b6dacbb1d112c42aaa63c0837654a56d4afdd9eb442bc7000f3ceda90fb254aea5712a5e2d3aeff58d1505d869957a3
+  data.tar.gz: 1be4b42da76e635d82ee95f663ea9ca950873b2c6037779598cfa0c284076a022a05aaeb772dd66f5a08b76bedbac7be3ac27453db0a07a4be8e7e0b3213bca9

data/README.md

@@ -197,7 +197,22 @@ Documents the responses of the endpoint and overrides the default responses foun
 
 `# @response User not found by the provided Id(404) [Hash{success: Boolean, message: String}]`
 
-`# @response Validation errors(422) [Hash{success: Boolean, erros: Array<Hash{field: String, type: String, detail: Array<String>}>}]`
+`# @response Validation errors(422) [Hash{success: Boolean, errors: Array<Hash{field: String, type: String, detail: Array<String>}>}]`
+
+</details>
+
+<details>
+<summary style="font-weight: bold; font-size: 1.2em;">@response_example</summary>
+
+**Structure**: `@response_example text(code) [String Hash]`
+
+Documents response examples of the endpoint associated to a response code.
+
+**Example**:
+
+`# @response_example Invalida Email(422) [{success: "false", errors: [{field: "email", type: "email", detail: ["Invalid email"]}] }]`
+
+`# @response_example Id not exists (404) [{success: "false", message: "Nothing found with the provided ID." }]`
 
 </details>
 

data/lib/oas_rails/builders/responses_builder.rb

@@ -8,7 +8,10 @@ module OasRails
 
       def from_oas_route(oas_route)
         oas_route.docstring.tags(:response).each do |tag|
-          @responses.add_response(ResponseBuilder.new(@specification).from_tag(tag).build)
+          content = ContentBuilder.new(@specification, :outgoing).with_schema(tag.schema).with_examples_from_tags(oas_route.docstring.tags(:response_example).filter { |re| re.code == tag.name }).build
+          response = ResponseBuilder.new(@specification).with_code(tag.name.to_i).with_description(tag.text).with_content(content).build
+
+          @responses.add_response(response)
         end
 
         self

data/lib/oas_rails/configuration.rb

@@ -26,7 +26,7 @@ module OasRails
       @security_schemas = {}
       @set_default_responses = true
       @possible_default_responses = [:not_found, :unauthorized, :forbidden]
-      @response_body_of_default = "{ message: String }"
+      @response_body_of_default = "Hash{ success: !Boolean, message: String }"
     end
 
     def security_schema=(value)

data/lib/oas_rails/version.rb

@@ -1,3 +1,3 @@
 module OasRails
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/lib/oas_rails/yard/example_tag.rb

@@ -0,0 +1,12 @@
+module OasRails
+  module YARD
+    class ExampleTag < ::YARD::Tags::Tag
+      attr_accessor :content
+
+      def initialize(tag_name, text, content: {})
+        super(tag_name, text, nil, nil)
+        @content = content
+      end
+    end
+  end
+end

data/lib/oas_rails/yard/oas_rails_factory.rb

@@ -37,6 +37,15 @@ module OasRails
         ResponseTag.new(tag_name, code, name, schema)
       end
 
+      # Parses a tag that represents a response example.
+      # @param tag_name [String] The name of the tag.
+      # @param text [String] The tag text to parse.
+      # @return [ResponseExampleTag] The parsed response example tag object.
+      def parse_tag_with_response_example(tag_name, text)
+        description, code, hash = extract_name_code_and_hash(text)
+        ResponseExampleTag.new(tag_name, description, content: hash, code:)
+      end
+
       private
 
       # Reusable method for extracting description, type, and content with an option to process content.
@@ -44,7 +53,7 @@ module OasRails
       # @param process_content [Boolean] Whether to evaluate the content as a hash.
       # @return [Array] An array containing the description, type, and content or remaining text.
       def extract_description_type_and_content(text, process_content: false)
-        match = text.match(/^(.*?)\s*\[(.*?)\]\s*(.*)$/)
+        match = text.match(/^(.*?)\s*\[(.*)\]\s*(.*)$/)
         raise ArgumentError, "Invalid tag format: #{text}" if match.nil?
 
         description = match[1].strip
@@ -84,6 +93,16 @@ module OasRails
         [name, code, schema]
       end
 
+      # Specific method to extract name, code, and hash for responses examples.
+      # @param text [String] The text to parse.
+      # @return [Array] An array containing the name, code, and schema.
+      def extract_name_code_and_hash(text)
+        name, code = extract_text_and_parentheses_content(text)
+        _, type, = extract_description_type_and_content(text)
+        hash = eval_content(type)
+        [name, code, hash]
+      end
+
       # Evaluates a string as a hash, handling errors gracefully.
       # @param content [String] The content string to evaluate.
       # @return [Hash] The evaluated hash, or an empty hash if an error occurs.

data/lib/oas_rails/yard/request_body_example_tag.rb

@@ -1,11 +1,10 @@
 module OasRails
   module YARD
-    class RequestBodyExampleTag < ::YARD::Tags::Tag
+    class RequestBodyExampleTag < ExampleTag
       attr_accessor :content
 
       def initialize(tag_name, text, content: {})
-        super(tag_name, text, nil, nil)
-        @content = content
+        super
       end
     end
   end

data/lib/oas_rails/yard/response_example_tag.rb

@@ -0,0 +1,12 @@
+module OasRails
+  module YARD
+    class ResponseExampleTag < ExampleTag
+      attr_accessor :code
+
+      def initialize(tag_name, text, content: {}, code: 200)
+        super(tag_name, text, content:)
+        @code = code
+      end
+    end
+  end
+end

data/lib/oas_rails/yard/response_tag.rb

@@ -3,6 +3,7 @@ module OasRails
     class ResponseTag < ::YARD::Tags::Tag
       attr_accessor :schema
 
+      # TODO: name == code. The name MUST be changed to code for better understanding
       def initialize(tag_name, name, text, schema)
         super(tag_name, text, nil, name)
         @schema = schema

data/lib/oas_rails.rb

@@ -47,9 +47,11 @@ module OasRails
 
   module YARD
     autoload :RequestBodyTag, 'oas_rails/yard/request_body_tag'
+    autoload :ExampleTag, 'oas_rails/yard/example_tag'
     autoload :RequestBodyExampleTag, 'oas_rails/yard/request_body_example_tag'
     autoload :ParameterTag, 'oas_rails/yard/parameter_tag'
     autoload :ResponseTag, 'oas_rails/yard/response_tag'
+    autoload :ResponseExampleTag, 'oas_rails/yard/response_example_tag'
     autoload :OasRailsFactory, 'oas_rails/yard/oas_rails_factory'
   end
 
@@ -84,6 +86,7 @@ module OasRails
         'Request body Example' => [:request_body_example, :with_request_body_example],
         'Parameter' => [:parameter, :with_parameter],
         'Response' => [:response, :with_response],
+        'Response Example' => [:response_example, :with_response_example],
         'Endpoint Tags' => [:tags],
         'Summary' => [:summary],
         'No Auth' => [:no_auth],

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: oas_rails
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - a-chacon
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-08-23 00:00:00.000000000 Z
+date: 2024-08-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: method_source
@@ -130,10 +130,12 @@ files:
 - lib/oas_rails/spec/tag.rb
 - lib/oas_rails/utils.rb
 - lib/oas_rails/version.rb
+- lib/oas_rails/yard/example_tag.rb
 - lib/oas_rails/yard/oas_rails_factory.rb
 - lib/oas_rails/yard/parameter_tag.rb
 - lib/oas_rails/yard/request_body_example_tag.rb
 - lib/oas_rails/yard/request_body_tag.rb
+- lib/oas_rails/yard/response_example_tag.rb
 - lib/oas_rails/yard/response_tag.rb
 homepage: https://github.com/a-chacon/oas_rails
 licenses: