oas_rails 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e873607a5e36e6301251d74b2754c71d0c2b2e3591afcc7f4d3c8135be4f1c3
-  data.tar.gz: e3f242451e51b13bc2b05b00ab9e5c440f8a139914ec567e6547fa14f8a6c09e
+  metadata.gz: 3ce2a79462161474eeb19ee711b0bdf11615c64e5695732587ebecfeef8a5c3f
+  data.tar.gz: 7f6df06bb7de5dffaf94019e3ba9f9bab2cc59d17b72573f69f945635b435291
 SHA512:
-  metadata.gz: 66c4beb422b09cc0c801433897f892a7e52284fefbfd5598220e893d3ebdf6a026c68d54613cf4c7ab920e6cc320ba7f331ae1bc4c9dd9f4002df9d41183e79f
-  data.tar.gz: 60faac4dfba6f28e9ac45f4c37f1879b3bd5a4136baee262ee0a950fb824128047f514cda2845623b64be3bccf5a6407234060846882f7a1033e4720a56afc52
+  metadata.gz: c4e58fd69b4ebc8903541e2c9bef51b435c578e18af5a05c3c63f5faf7fad11defabd35bfb4a129b4977bd034a5f432661b3d5c1f81ee6fb8462b81741f187ba
+  data.tar.gz: 599a61527af3f05fe535d57c7016b00a52046564b4d792c40bb9b5aa7413917d2898f36da20bf3e7064f480ab45ffcd095f9168f0865cad7397aebec3aba9256

data/README.md

@@ -10,7 +10,7 @@
 OasRails is a Rails engine for generating **automatic interactive documentation for your Rails APIs**. It generates an **OAS 3.1** document and displays it using **[RapiDoc](https://rapidocweb.com)**.
 
 🎬 A Demo Video Here:
-https://vimeo.com/1013687332
+<https://vimeo.com/1013687332>
 🎬
 
 ![Screenshot](https://a-chacon.com/assets/images/oas_rails_ui.png)
@@ -80,7 +80,7 @@ You'll now have **basic documentation** based on your routes and automatically g
 
 ## ⚙️ Configuration
 
-To configure OasRails, you MUST create an initializer file including all your settings. The first step is to create your initializer file, which you can easily do with:
+To configure OasRails, **you MUST create an initializer file** including all your settings. The first step is to create your initializer file, which you can easily do with:
 
 ```bash
 rails generate oas_rails:config
@@ -135,7 +135,20 @@ In addition to the information provided in the initializer file and the data tha
 
 ### Documenting Your Endpoints
 
-Almost every description in an OAS file supports simple markdown. The following tags are available for documenting your endpoints:
+Almost every tag description in an OAS file supports **markdown formatting** (e.g., bold, italics, lists, links) for better readability in the generated documentation. Additionally, **multi-line descriptions** are supported. When using multi-line descriptions, ensure the content is indented at least one space more than the tag itself to maintain proper formatting.
+
+For example:
+
+```ruby
+  # @request_body_example Simple User [Hash]
+  #   {
+  #     user: {
+  #       name: "Oas",
+  #       email: "oas@test.com",
+  #       password: "Test12345"
+  #     }
+  #   }
+```
 
 <details>
 <summary style="font-weight: bold; font-size: 1.2em;">@summary</summary>
@@ -145,8 +158,14 @@ Almost every description in an OAS file supports simple markdown. The following
 Used to add a summary to the endpoint. It replaces the default summary/title of the endpoint.
 
 **Example**:
+
 `# @summary This endpoint creates a User`
 
+```
+# @summary This endpoint
+#   creates a User
+```
+
 </details>
 
 <details>
@@ -169,15 +188,31 @@ Represents a parameter for the endpoint. The position can be: `header`, `path`,
 
 Documents the request body needed by the endpoint. The structure is optional if you provide a valid Active Record class. Use `!` to indicate a required request body.
 
-**Example**:
-
-`# @request_body The user to be created [!Hash{user: Hash{name: String, age: Integer, password: String}}]`
+**One line example**:
 
 `# @request_body The user to be created [!User]`
 
 `# @request_body The user to be created [User]`
 
-`# @request_body The user to be created [!Hash{user: Hash{name: String, age: Integer, password: String, surnames: Array<String>, coords: Hash{lat: String, lng: String}}}]`
+**Multi-line example**:
+
+```ruby
+  # @request_body User to be created
+  #   [
+  #     !Hash{
+  #       user: Hash{
+  #         name: String,
+  #         email: String,
+  #         age: Integer,
+  #         cars: Array<
+  #           Hash{
+  #             identifier: String
+  #           }
+  #         >
+  #       }
+  #     }
+  #   ]
+```
 
 </details>
 
@@ -188,9 +223,23 @@ Documents the request body needed by the endpoint. The structure is optional if
 
 Adds examples to the provided request body.
 
-**Example**:
+**One line example**:
+
 `# @request_body_example A complete User. [Hash] {user: {name: 'Luis', age: 30, password: 'MyWeakPassword123'}}`
 
+**Multi-line example**:
+
+```ruby
+  # @request_body_example basic user [Hash]
+  #   {
+  #     user: {
+  #       name: "Oas",
+  #       email: "oas@test.com",
+  #       password: "Test12345"
+  #     }
+  #   }
+```
+
 </details>
 
 <details>
@@ -200,12 +249,27 @@ Adds examples to the provided request body.
 
 Documents the responses of the endpoint and overrides the default responses found by the engine.
 
-**Example**:
+**One line example**:
 
 `# @response User not found by the provided Id(404) [Hash{success: Boolean, message: String}]`
 
 `# @response Validation errors(422) [Hash{success: Boolean, errors: Array<Hash{field: String, type: String, detail: Array<String>}>}]`
 
+**Multi-line example**:
+
+```ruby
+  # @response A test response from an Issue(405)
+  #   [
+  #     Hash{
+  #       message: String,
+  #       data: Hash{
+  #         availabilities: Array<String>,
+  #         dates: Array<Date>
+  #       }
+  #     }
+  #   ]
+```
+
 </details>
 
 <details>
@@ -215,12 +279,27 @@ Documents the responses of the endpoint and overrides the default responses foun
 
 Documents response examples of the endpoint associated to a response code.
 
-**Example**:
+**One line 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." }]`
 
+**Multi-line example**:
+
+```ruby
+  # @response_example Another 405 Error (405) [Hash]
+  #   {
+  #     message: "another",
+  #     data: {
+  #       availabilities: [
+  #         "three"
+  #       ],
+  #       dates: []
+  #     }
+  #   }
+```
+
 </details>
 
 <details>
@@ -282,9 +361,9 @@ class UsersController < ApplicationController
   # This method show a User by ID. The id must exist of other way it will be returning a **`404`**.
   #
   # @parameter id(path) [Integer] Used for identify the user.
-  # @response Requested User(200) [Hash{user: {name: String, email: String, created_at: DateTime }}]
-  # @response User not found by the provided Id(404) [Hash{success: Boolean, message: String}]
-  # @response You don't have the right permission for access to this resource(403) [Hash{success: Boolean, message: String}]
+  # @response Requested User(200) [Hash] {user: {name: String, email: String, created_at: DateTime }}
+  # @response User not found by the provided Id(404) [Hash] {success: Boolean, message: String}
+  # @response You don't have the right permission for access to this resource(403) [Hash] {success: Boolean, message: String}
   def show
     render json: @user
   end
@@ -409,6 +488,8 @@ Once the custom view file is in place, Rails will automatically use it instead o
 
 Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**. If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star⭐! Thanks again!
 
+If you plan a big feature, first open an issue to discuss it before any development.
+
 1. Fork the Project
 2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
 3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
@@ -417,14 +498,14 @@ Contributions are what make the open source community such an amazing place to l
 
 ### Roadmap and Ideas for Improvement
 
-- Clean, document and structure the code
+- [ ] Clean, document and structure the code
 - [x] Support documentation of authentication methods
-- Define Global Tags/Configuration (e.g., common responses like 404 errors)
-- Post-process the JSON and replace common objects with references to components
-- Create a temporary file with the JSON in production mode to avoid rebuilding it on every request
-- Create tags for popular gems used in APIs (e.g., a `@pagy` tag for common pagination parameters)
+- [ ] Define Global Tags/Configuration (e.g., common responses like 404 errors)
+- [ ] Post-process the JSON and replace common objects with references to components
+- [ ] Create a temporary file with the JSON in production mode to avoid rebuilding it on every request
+- [ ] Create tags for popular gems used in APIs (e.g., a `@pagy` tag for common pagination parameters)
 - [x] Add basic authentication to OAS and UI for security reasons (Solution documented, not need to be managed by the engine)
-- Implement ability to define OAS by namespaces (e.g., generate OAS for specific routes like `/api` or separate versions V1 and V2)
+- [ ] Implement ability to define OAS by namespaces (e.g., generate OAS for specific routes like `/api` or separate versions V1 and V2)
 
 ## License
 

data/lib/oas_rails/builders/esquema_builder.rb

@@ -6,22 +6,23 @@ module OasRails
         #
         # @param klass [Class] The class for which the schema is built.
         # @return [Hash] The schema as a JSON-compatible hash.
-        def build_incoming_schema(klass:, model_to_schema_class: Esquema)
-          configure_common_settings
+        def build_incoming_schema(klass:, model_to_schema_class: EasyTalk)
+          configure_common_settings(model_to_schema_class:)
           model_to_schema_class.configuration.excluded_columns = OasRails.config.excluded_columns_incoming
 
-          model_to_schema_class::Builder.new(klass).build_schema.as_json
+          model_to_schema_class::ActiveRecordSchemaBuilder.new(klass).build_schema_definition.as_json["schema"]
         end
 
         # Builds a schema for a class when it is used as outgoing API data.
         #
         # @param klass [Class] The class for which the schema is built.
         # @return [Hash] The schema as a JSON-compatible hash.
-        def build_outgoing_schema(klass:, model_to_schema_class: Esquema)
-          configure_common_settings
+        def build_outgoing_schema(klass:, model_to_schema_class: EasyTalk)
+          configure_common_settings(model_to_schema_class:)
           model_to_schema_class.configuration.excluded_columns = OasRails.config.excluded_columns_outgoing
+          model_to_schema_class.configuration.exclude_primary_key = false
 
-          model_to_schema_class::Builder.new(klass).build_schema.as_json
+          model_to_schema_class::ActiveRecordSchemaBuilder.new(klass).build_schema_definition.as_json["schema"]
         end
 
         private
@@ -29,9 +30,9 @@ module OasRails
         # Configures common settings for schema building.
         #
         # Excludes associations and foreign keys from the schema.
-        def configure_common_settings
-          Esquema.configuration.exclude_associations = true
-          Esquema.configuration.exclude_foreign_keys = true
+        def configure_common_settings(model_to_schema_class: EasyTalk)
+          model_to_schema_class.configuration.exclude_associations = true
+          model_to_schema_class.configuration.exclude_foreign_keys = true
         end
       end
     end

data/lib/oas_rails/oas_route.rb

@@ -25,9 +25,11 @@ module OasRails
     end
 
     def extract_docstring
-      ::YARD::Docstring.parser.parse(
-        controller_class.constantize.instance_method(method).comment.lines.map { |line| line.sub(/^#\s*/, '') }.join
-      ).to_docstring
+      comment_lines = controller_class.constantize.instance_method(method).comment.lines
+      processed_lines = comment_lines.map do |line|
+        line.sub(/^# /, '')
+      end
+      ::YARD::Docstring.parser.parse(processed_lines.join).to_docstring
     end
 
     def extract_source_string

data/lib/oas_rails/spec/media_type.rb

@@ -68,7 +68,11 @@ module OasRails
         def fetch_fixture_examples(klass:)
           fixture_file = Rails.root.join('test', 'fixtures', "#{klass.to_s.pluralize.downcase}.yml")
           begin
-            fixture_data = YAML.load_file(fixture_file).with_indifferent_access
+            erb_result = ERB.new(File.read(fixture_file)).result
+            fixture_data = YAML.safe_load(
+              erb_result,
+              permitted_classes: [Symbol, ActiveSupport::HashWithIndifferentAccess]
+            ).with_indifferent_access
           rescue Errno::ENOENT
             return {}
           end

data/lib/oas_rails/utils.rb

@@ -34,6 +34,7 @@ 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]

data/lib/oas_rails/version.rb

@@ -1,3 +1,3 @@
 module OasRails
-  VERSION = "0.9.0"
+  VERSION = "0.10.0"
 end

data/lib/oas_rails/yard/oas_rails_factory.rb

@@ -6,7 +6,7 @@ module OasRails
       # @param text [String] The tag text to parse.
       # @return [RequestBodyTag] The parsed request body tag object.
       def parse_tag_with_request_body(tag_name, text)
-        description, klass, schema, required = extract_description_and_schema(text)
+        description, klass, schema, required = extract_description_and_schema(text.squish)
         RequestBodyTag.new(tag_name, description, klass, schema:, required:)
       end
 
@@ -15,7 +15,7 @@ module OasRails
       # @param text [String] The tag text to parse.
       # @return [RequestBodyExampleTag] The parsed request body example tag object.
       def parse_tag_with_request_body_example(tag_name, text)
-        description, _, hash = extract_description_type_and_content(text, process_content: true, expresion: /^(.*?)\[([^\]]*)\](.*)$/m)
+        description, _, hash = extract_description_type_and_content(text.squish, process_content: true, expresion: /^(.*?)\[([^\]]*)\](.*)$/m)
         RequestBodyExampleTag.new(tag_name, description, content: hash)
       end
 
@@ -24,7 +24,8 @@ module OasRails
       # @param text [String] The tag text to parse.
       # @return [ParameterTag] The parsed parameter tag object.
       def parse_tag_with_parameter(tag_name, text)
-        name, location, schema, required, description = extract_name_location_schema_and_description(text)
+        name, location, schema, required, description = extract_name_location_schema_and_description(text.squish)
+        name = "#{name}[]" if location == "query" && schema[:type] == "array"
         ParameterTag.new(tag_name, name, description, schema, location, required:)
       end
 
@@ -33,7 +34,7 @@ module OasRails
       # @param text [String] The tag text to parse.
       # @return [ResponseTag] The parsed response tag object.
       def parse_tag_with_response(tag_name, text)
-        name, code, schema = extract_name_code_and_schema(text)
+        name, code, schema = extract_name_code_and_schema(text.squish)
         ResponseTag.new(tag_name, code, name, schema)
       end
 
@@ -42,7 +43,7 @@ module OasRails
       # @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)
+        description, code, hash = extract_name_code_and_hash(text.squish)
         ResponseExampleTag.new(tag_name, description, content: hash, code:)
       end
 
@@ -98,8 +99,8 @@ module OasRails
       # @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)
+        _, _, content = extract_description_type_and_content(text, expresion: /^(.*?)\[([^\]]*)\](.*)$/m)
+        hash = eval_content(content)
         [name, code, hash]
       end
 

data/lib/oas_rails.rb

@@ -1,6 +1,6 @@
 require "yard"
 require "method_source"
-require "esquema"
+require "easy_talk"
 
 module OasRails
   require "oas_rails/version"

metadata

@@ -1,17 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: oas_rails
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - a-chacon
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-01-29 00:00:00.000000000 Z
+date: 2025-03-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: method_source
+  name: easy_talk
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
@@ -25,19 +25,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.0'
 - !ruby/object:Gem::Dependency
-  name: model-to-schema
+  name: method_source
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.1.2
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.1.2
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement