jbuilder-schema 2.6.7 → 2.6.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9df1e47129d5125d222c0f9b5fc39a678b1034814198d86f8ac9e661014d12e9
-  data.tar.gz: 5724904ce752c19d7f9ef70bfca632996edc9c840fbdb9752259941f955808c7
+  metadata.gz: dc6b74ad43767a8a12d27263b224beb94b8a3aa4deab865e81fb2753ff367718
+  data.tar.gz: 03243e798c0e28991c926b52b90d448b79d7f66aa0f59b997d9fd384b5d4bd28
 SHA512:
-  metadata.gz: 615e44bdebeb69b360ded48ae49a6450d39662cbe66c2f3061535934d0be2f7b2945a225082bb7cab2e975826c99ac724d7c98830e832be9ce58f73cc1afa23c
-  data.tar.gz: 21b333cccdad9e9e1cde19b61f9424b9d3c7624766241185ac4046138a0da2df66de98fc7f5846c6c1c1f05ff0ac753da9f1173b6551f2884d7482a5a35d628b
+  metadata.gz: aaa65e842309918131ba5ae7f01f2063dcd9312505d9677a1037bab01801b8eab1865b8cd00daeca3712cbf367dd5494526939468623b4b1af706c86ac6c5751
+  data.tar.gz: a12318b8132a8a6edca71fcfe746dc6a757afe7a105405c17ca9ba22683ad7ebd51c4978bad692ab90c81f14d242ebf0dba016d6ff4e9fc039cc9b816ed007e5

data/README.md

@@ -1,62 +1,58 @@
 # Jbuilder::Schema
 
-Generate JSON Schema compatible with OpenAPI 3 specs from Jbuilder files
+Easily Generate OpenAPI 3.1 Schemas from Jbuilder Templates
 
-## Installation
+## Quick Start
 
-In your Gemfile, put `gem "jbuilder-schema"` after Jbuilder:
+### Installation
+
+Add this to your Gemfile:
 
     gem "jbuilder"
     gem "jbuilder-schema"
 
-And run:
-
-    $ bundle
-
-Or install it yourself as:
+Then, run `bundle` or install it manually using `gem install jbuilder-schema`.
 
-    $ gem install jbuilder-schema
+### Generating Schemas
 
-## Usage
-
-Wherever you want to generate schemas, call `Jbuilder::Schema.yaml` or `Jbuilder::Schema.json`:
+Use `Jbuilder::Schema.yaml` or `Jbuilder::Schema.json` to create schemas. For example:
 
 ```ruby
 Jbuilder::Schema.yaml(@article, title: 'Article', description: 'Article in the blog', locals: { current_user: @user })
 ```
 
-Under the hood `Jbuilder::Schema.yaml`/`json` will use Action View's `render` method and support the same arguments.
+This will render a Jbuilder template (e.g., `articles/_article.json.jbuilder`) and make `@article` available in the partial. You can also pass additional locals.
 
-So in the above example, the `@article`'s `to_partial_path` path is used to find and render a `articles/_article.json.jbuilder` template, and `article` is available in the partial.
+## Contents
 
-Additionally, we can pass any needed `locals:`.
+- [Advanced Usage](#advanced-usage)
+    - [Rendering Specific Directories](#rendering-specific-directories)
+    - [Rendering Templates](#rendering-templates)
+- [Output](#output)
+- [Handling Arrays and Objects](#handling-arrays-and-objects)
+- [Nested Partials and Arrays](#nested-partials-and-arrays)
+- [Customization](#customization)
+    - [Titles & Descriptions](#titles--descriptions)
+- [Configuration](#configuration)
+- [Integration with RSwag](#integration-with-rswag)
+- [Contributing](#contributing)
+- [License](#license)
+- [Sponsor](#open-source-development-sponsored-by)
 
-The `title` and `description` set the title and description of the schema — though they can also come from locale files (see *[Titles & Descriptions](#titles--descriptions)*);
+### Advanced Usage
 
-### Use with a directory within app/views
+#### Rendering Specific Directories
 
-If you have a directory within app/views where your Jbuilder templates are, you can use `renderer` to capture that along with any `locals:` common to the templates you'll render:
+If your Jbuilder templates are in a specific directory, use `Jbuilder::Schema.renderer`:
 
 ```ruby
 jbuilder = Jbuilder::Schema.renderer('app/views/api/v1', locals: { current_user: @user })
 jbuilder.yaml @article, title: 'Article', description: 'Article in the blog'
 ```
 
-This means you don't have to write out the partial path, which gets tedious with multiple schema renders:
+#### Rendering Templates
 
-```ruby
-Jbuilder::Schema.yaml(partial: 'api/v1/articles/article', locals: { article: @article, current_user: @user }, title: 'Article', description: 'Article in the blog')
-```
-
-### Rendering a template
-
-If you're rendering a template like `app/views/articles/index.jbuilder`:
-
-```ruby
-json.articles @articles, :id, :title
-```
-
-You'll need to pass the relative template path in `template:` and any needed instance variables in `assigns:` like so:
+For templates like `app/views/articles/index.jbuilder`, specify the template path and variables:
 
 ```ruby
 Jbuilder::Schema.yaml(template: "articles/index", assigns: { articles: Article.first(3) })
@@ -64,15 +60,16 @@ Jbuilder::Schema.yaml(template: "articles/index", assigns: { articles: Article.f
 
 ### Output
 
-Jbuilder::Schema automatically sets `description`, `type`, and `required` options in JSON-Schema.
+Jbuilder::Schema automatically sets `description`, `type`, and `required` fields in the JSON Schema. You can *[customize](#customization)* these using the `schema:` hash.
 
-For example, if we have a `_article.json.jbuilder` file:
+#### Example
 
 ```ruby
+# _article.json.jbuilder
 json.extract! article, :id, :title, :body, :created_at
 ```
 
-This will produce the following:
+#### Result
 
 ```yaml
 type: object
@@ -84,148 +81,261 @@ required:
   - body
 properties:
   id:
-    description: ID of an article
     type: integer
+    description: Article ID
   title:
-    description: Title of an article
     type: string
+    description: Article Title
   body:
-    description: Contents of an article
     type: string
+    description: Article Contents
   created_at:
-    description: Timestamp when article was created
-    type: string
+    type:
+      - string
+      - "null"
     format: date-time
+    description: Timestamp when article was created
 ```
 
-### Customization
+### Handling Arrays and Objects
+
+The gem efficiently handles arrays and objects, including nested structures. Arrays with a single element type are straightforwardly represented, while arrays with mixed types use the `anyOf` keyword for versatility.
 
-#### Simple
+Support of various object types like `Hash`, `Struct`, `OpenStruct`, and `ActiveRecord::Base` is also integrated. It simplifies object schemas by setting only `type` and `properties`.
 
-To set your own data in the generated JSON-Schema pass a `schema:` hash:
+#### Example
 
 ```ruby
-json.id article.id, schema: { type: :number, description: "Custom ID description" }
-json.title article.title, schema: { minLength: 5, maxLength: 20 }
-json.body article.body, schema: { type: :text, maxLength: 500 }
-json.created_at article.created_at.strftime('%d/%m/%Y'), schema: { format: :date, pattern: /^(3[01]|[12][0-9]|0[1-9])\/(1[0-2]|0[1-9])\/[0-9]{4}$/ }
+json.custom_array [1, article.user, 2, "Text", [3.14, 25.44], 5.33, [3, "Another text", {a: 4, b: "One more text"}], {c: 5, d: "And another"}, {e: 6, f: {g: 7, h: "Last Text"}}]
 ```
 
-This will produce the following:
+#### Result
 
 ```yaml
-...
-  properties:
-    id:
-      description: Custom ID description
-      type: number
-    title:
-      description: Title of an article
-      type: string
-      minLength: 5
-      maxLength: 20
-    body:
-      description: Contents of an article
-      type: string
-      maxLength: 500
-    created_at:
-      description: Timestamp when article was created
-      type: string
-      format: date
-      pattern: "^(3[01]|[12][0-9]|0[1-9])\/(1[0-2]|0[1-9])\/[0-9]{4}$"
+properties:
+  custom_array:
+    type:
+      - array
+      - "null"
+    minContains: 0
+    contains:
+      anyOf:
+        - type: integer
+        - type: object
+          # ... ActiveRecord object properties ...
+        - type: string
+        - type: array
+          # All arrays are merged in one so all possible values of arrays are in one place
+          minContains: 0
+          contains:
+            anyOf:
+              - type: number
+              - type: integer
+              - type: string
+              - type: object
+                properties:
+                  a:
+                    type: integer
+                    # ... description ...
+                  b:
+                    type: integer
+                    # ... description ...
+        - type: number
+        - type: object
+          properties:
+            c:
+              type: integer
+              # ... description ...
+            d:
+              type: integer
+              # ... description ...
+        - type: object
+          properties:
+            e:
+              type: integer
+              # ... description ...
+            f:
+              type: object
+              properties:
+                h:
+                  type: integer
+                  # ... description ...
+                g:
+                  type: string
+                  # ... description ...
+    description: Very weird custom array
 ```
 
-#### Bulk
-
-You can customize output for multiple fields at once:
+Each schema is unique, ensuring no duplication. Description fields are nested under parent field names for clarity.
 
-```ruby
-json.extract! user, :id, :name, :email, schema: {id: {type: :string}, email: {type: :email, pattern: /^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$/}}
-```
+### Nested Partials and Arrays
 
-### Nested objects
+Nested partials and arrays will most commonly produce reference to the related schema component.
+Only if block with partial includes other fields, the inline object will be generated.
 
-When you have nested objects in your Jbuilder template, you have to pass it to `schema: {object: <nested_object>}` when the block starts:
+#### Example
 
 ```ruby
-json.extract! article
-json.author schema: {object: article.user, object_title: "Author", object_description: "Authors are users who write articles"} do
-  json.extract! article.user
+json.author do
+  json.partial! "api/v1/users/user", user: article.user
+end
+json.comments do
+  json.array! article.comments, partial: "api/v1/articles/comments/comment", as: :article_comment
+end
+json.ratings do
+    json.array! article.ratings, schema: {object: article.ratings.first, title: "Rating", description: "Article Rating"} do |rating|
+      json.partial! "api/v1/shared/id", resource: rating
+      json.extract! rating, :value
+    end
 end
 ```
 
-This will help Jbuilder::Schema to process those fields right.
+#### Result
+
+```yaml
+# ... object description ...
+properties:
+  author:
+    type: object
+    allOf:
+      - "$ref": "#/components/schemas/User"
+    description: User
+  comments:
+    type: array
+    items:
+      - "$ref": "#/components/schemas/Comment"
+    description: Comments
+  ratings:
+    type: array
+    items:
+      type: object
+      title: Rating
+      description: Article Rating
+      required:
+        - id
+        - value
+      properties:
+        id:
+          type: integer
+          description: Rating ID
+        public_id:
+          type:
+            - string
+            - "null"
+          description: Rating Public ID
+        value:
+          type: integer
+          description: Rating Value
+    description: Article Ratings
+```
 
-### Collections
+Reference names are taken from `:as` option or first of the `locals:`.
 
-If an object or an array of objects is generated in template, either in root or in some field through Jbuilder partials, JSON-Schema `$ref` is generated pointing to object with the same name as partial. By default those schemas should appear in `"#/components/schemas/"`.
+The path to component schemas can be configured with `components_path` variable, which defaults to `components/schemas`. See *[Configuration](#configuration)* for more info.
 
-For example, if we have:
+### Customization
+
+Customize individual or multiple fields at once using the `schema:` attribute.
+For nested objects and collections, use the `schema: {object: <nested_object>}` format.
+
+#### Example
 
 ```ruby
-json.user do
-  json.partial! 'api/v1/users/user', user: user
-end
+json.id article.id, schema: { type: :number, description: "Custom ID description" }
+json.title article.title, schema: { minLength: 5, maxLength: 20 }
+json.contents article.body, schema: { type: :text, maxLength: 500, required: true }
+json.created_at article.created_at.strftime('%d/%m/%Y'), schema: { format: :date, pattern: /^(3[01]|[12][0-9]|0[1-9])\/(1[0-2]|0[1-9])\/[0-9]{4}$/ }
 
-json.articles do
-  json.array! user.articles, partial: "api/v1/articles/article", as: :article
+json.author schema: {object: article.user, title: "Article Author", description: "The person who wrote the article", required: true} do
+  json.extract! article.user, :id, :name, :email, schema: {id: {type: :string}, email: {type: :email, pattern: /^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$/}}
 end
 ```
 
-The result would be:
+#### Result
 
 ```yaml
-user:
-  type: object
-  $ref: #/components/schemas/user
-articles:
-  type: array
-  items:
-    $ref: #/components/schemas/article
+type: object
+title: Article
+description: Article in the blog
+required:
+  - id
+  - title
+  - contents
+  - author
+properties:
+  id:
+    type: number
+    description: Custom ID description
+  title:
+    type: string
+    minLength: 5
+    maxLength: 20
+    description: Title of an article
+  contents:
+    type: string
+    maxLength: 500
+    description: Contents of an article
+  created_at:
+    type:
+      - string
+      - "null"
+    format: date
+    pattern: "^(3[01]|[12][0-9]|0[1-9])\/(1[0-2]|0[1-9])\/[0-9]{4}$"
+    description: Timestamp when article was created
+  author:
+    type: object
+    title: Article Author
+    description: The person who wrote the article
+    required:
+      - id
+      - name
+      - email
+    properties:
+      id:
+        type: string
+        description: User ID
+      name:
+        type: string
+        description: User Name
+      email:
+        type: email
+        pattern: "^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$"
+        description: User Email
 ```
 
-The path to component schemas can be configured with `components_path` variable, which defaults to `components/schemas`. See *[Configuration](#configuration)* for more info.
-
-### Titles & Descriptions
+#### Titles & Descriptions
 
-Custom titles and descriptions for objects can be specified when calling `jbuilder-schema` helper (see *[Usage](#usage)*), for fields and nested objects within `schema` attributes (see *[Customization](#simple)* and *[Nested objects](#nested-objects)*). If not set, they will be searched in locale files.
-
-Titles and descriptions for the models are supposed to be found in locale files under `<underscored_plural_model_name>.<title_name>` and `<underscored_plural_model_name>.<description_name>`, for example:
+Set custom titles and descriptions directly or through locale files. For models, use `<underscored_plural_model_name>.<title_name>` and for fields, use `<underscored_plural_model_name>.fields.<field_name>.<description_name>` in locale files:
 
 ```yaml
 en:
   articles:
     title: Article
     description: The main object on the blog
-```
-
-Descriptions for the fields are supposed to be found in locale files under `<underscored_plural_model_name>.fields.<field_name>.<description_name>`, for example:
-
-```yaml
-en:
-  articles:
     fields:
       title:
         description: The title of an article
 ```
 
-`<title_name>` and `<description_name>` can be configured (see *[Configuration](#configuration)*), it defaults to `title` and `description`.
-
 ### Configuration
 
-You can configure some variables that Jbuilder::Schema uses (for example, in `config/initializers/jbuilder_schema.rb`):
+Configure Jbuilder::Schema in `config/initializers/jbuilder_schema.rb`:
+
+The `title_name` and `description_name` parameters can accept either a single string or an array of strings. This feature provides the flexibility to specify fallback keys.
 
 ```ruby
 Jbuilder::Schema.configure do |config|
-  config.components_path = "components/schemas"   # could be "definitions/schemas"
-  config.title_name = "title"                     # could be "label"
-  config.description_name = "description"         # could be "heading"
+  config.components_path = "components/schemas" # could be "definitions/schemas"
+  config.title_name = "title" # could be "label", or an array to support fallbacks, like
+  config.description_name = %w[api_description description] # could be just string as well like "heading"
 end
 ```
 
-### RSwag
+With this configuration, the system will first try to find a translation for <underscored_plural_model_name>.fields.<field_name>.api_description. If it doesn't find a translation for this key, it will then attempt to find a translation for <underscored_plural_model_name>.fields.<field_name>.description.
+
+### Integration with RSwag
 
-You can use the `yaml`/`json` methods in your `swagger_helper.rb` like this:
+Use `yaml`/`json` methods in your `swagger_helper.rb` for Swagger documentation:
 
 ```ruby
 RSpec.configure do |config|
@@ -246,11 +356,11 @@ end
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/bullet-train-co/jbuilder-schema.
+Contributions are welcome! Report bugs and submit pull requests on [GitHub](https://github.com/bullet-train-co/jbuilder-schema).
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+This gem is open source under the [MIT License](https://opensource.org/licenses/MIT).
 
 ## Open-source development sponsored by:
 

data/lib/jbuilder/schema/template.rb

@@ -30,21 +30,39 @@ class Jbuilder::Schema
       end
 
       def title
-        super || translate(Jbuilder::Schema.title_name)
+        super || translate(title_keys)
       end
 
       def description
-        super || translate(Jbuilder::Schema.description_name)
+        super || translate(description_keys)
       end
 
-      def translate_field(key)
-        translate("fields.#{key}.#{Jbuilder::Schema.description_name}")
+      def translate_title(key)
+        translate(title_keys.map { |k| "fields.#{key}.#{k}" })
+      end
+
+      def translate_description(key)
+        translate(description_keys.map { |k| "fields.#{key}.#{k}" })
       end
 
       private
 
-      def translate(key)
-        I18n.t(key, scope: @scope ||= object&.class&.name&.underscore&.pluralize)
+      def translate(keys)
+        keys.each do |key|
+          translation = I18n.t(key, scope: @scope ||= object&.class&.name&.underscore&.pluralize, default: nil)
+          return translation if translation.present?
+        end
+        # FIXME: This produces `addresses/countries` for namespaced models.
+        # Should be probably `addresses.countries`
+        I18n.t(keys.first, scope: @scope ||= object&.class&.model_name&.collection)
+      end
+
+      def title_keys
+        Array(Jbuilder::Schema.title_name)
+      end
+
+      def description_keys
+        Array(Jbuilder::Schema.description_name)
       end
     end
 
@@ -84,6 +102,7 @@ class Jbuilder::Schema
 
     def set!(key, value = BLANK, *args, schema: nil, **options, &block)
       old_configuration, @configuration = @configuration, Configuration.build(**schema) if schema&.dig(:object)
+      _required << key if schema&.delete(:required) == true
       @within_block = _within_block?(&block)
 
       _with_schema_overrides(key => schema) do
@@ -188,16 +207,18 @@ class Jbuilder::Schema
       }
     end
 
-    def _set_description(key, value)
-      if !value.key?(:description) && @configuration.object
-        value[:description] = @configuration.translate_field(key)
-      end
+    def _set_title_and_description(key, value)
+      overrides = @schema_overrides&.dig(key)&.to_h || {}
+      return unless overrides.any? || @configuration.object
+
+      value[:title] ||= overrides[:title] if overrides.key?(:title)
+      value[:description] ||= overrides[:description] || @configuration.translate_description(key)
     end
 
-    def _set_ref(part, array: false)
-      ref = {"$ref": "#/#{::Jbuilder::Schema.components_path}/#{part.split("/").last}"}
+    def _set_ref(object, **options)
+      ref = {"$ref": "#/#{::Jbuilder::Schema.components_path}/#{object.split("/").last}"}
 
-      if array
+      if options[:array]
         _attributes.merge! type: :array, items: ref
       else
         _attributes.merge! type: :object, allOf: [ref]
@@ -209,6 +230,10 @@ class Jbuilder::Schema
       @attributes
     end
 
+    def _required
+      @required_keys ||= []
+    end
+
     FORMATS = {::DateTime => "date-time", ::ActiveSupport::TimeWithZone => "date-time", ::Date => "date", ::Time => "time"}
 
     def _schema(key, value, **options)
@@ -248,7 +273,7 @@ class Jbuilder::Schema
         options[:enum] = defined_enum.keys
       end
 
-      _set_description key, options unless within_array
+      _set_title_and_description key, options unless within_array
       options
     end
 
@@ -281,7 +306,7 @@ class Jbuilder::Schema
     def _set_value(key, value)
       value = _value(value)
       value = _schema(key, value) unless value.is_a?(::Hash) && (value.key?(:type) || value.key?(:allOf)) # rubocop:disable Style/UnlessLogicalOperators
-      _set_description(key, value)
+      _set_title_and_description(key, value)
       super
     end
 
@@ -296,10 +321,20 @@ class Jbuilder::Schema
     end
 
     def _required!(keys)
-      presence_validated_attributes = @configuration.object&.class.try(:validators).to_a.flat_map { _1.attributes if _1.is_a?(::ActiveRecord::Validations::PresenceValidator) }
+      presence_validated_attributes = @configuration.object&.class.try(:validators).to_a.flat_map { _1.attributes if _1.is_a?(::ActiveRecord::Validations::PresenceValidator) } + _required
       keys & [_key(:id), *presence_validated_attributes.flat_map { [_key(_1), _key("#{_1}_id")] }]
     end
 
+    def _within_block?(&block)
+      block.present? && _one_line?(block.source)
+    end
+
+    def _one_line?(text)
+      text = text.gsub("{", " do\n").gsub("}", "\nend").tr(";", "\n")
+      lines = text.lines[1..-2].reject { |line| line.strip.empty? || !line.strip.start_with?("json.") }
+      lines.size == 1
+    end
+
     ###
     # Jbuilder methods
     ###
@@ -317,15 +352,5 @@ class Jbuilder::Schema
 
       _merge_values(current_value, value)
     end
-
-    def _within_block?(&block)
-      block.present? && _one_line?(block.source)
-    end
-
-    def _one_line?(text)
-      text = text.gsub("{", " do\n").gsub("}", "\nend").tr(";", "\n")
-      lines = text.lines[1..-2].reject { |line| line.strip.empty? || line.strip.start_with?("#") }
-      lines.size == 1
-    end
   end
 end

data/lib/jbuilder/schema/version.rb

@@ -1,4 +1,4 @@
 # We can't use the standard `Jbuilder::Schema::VERSION =` because
 # `Jbuilder` isn't a regular module namespace, but a class …which also loads Active Support.
 # So we use trickery, and assign the proper version once `jbuilder/schema.rb` is loaded.
-JBUILDER_SCHEMA_VERSION = "2.6.7"
+JBUILDER_SCHEMA_VERSION = "2.6.9"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jbuilder-schema
 version: !ruby/object:Gem::Version
-  version: 2.6.7
+  version: 2.6.9
 platform: ruby
 authors:
 - Yuri Sidorov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-12-04 00:00:00.000000000 Z
+date: 2024-03-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jbuilder
@@ -89,7 +89,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
+rubygems_version: 3.5.6
 signing_key:
 specification_version: 4
 summary: Generate JSON Schema from Jbuilder files