blueprinter_schema 0.5.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 03c37dc53060c99e65e98088279e4e635bcedd8b495c9c9d4b31c624c7b56488
-  data.tar.gz: 5c82b98494016b536ed9e9f360353834c5daaf28e692a4a16fa8c5e466924733
+  metadata.gz: 624ef3521849ad9f4b406b1236f7466ca0938ae3b1070b831ab29ef87d0e759e
+  data.tar.gz: e71133b659e4fe5b40ff09319be9fe196894d698f8138811609eddfa4211a5f1
 SHA512:
-  metadata.gz: a118085debb64d40d46aae65e8c88ddc69c0e55e49949e580966618ea14b7573a05c02a0df47aa8cac4c09bb2872b50c002e7828b275954a045728fa56115d6e
-  data.tar.gz: b05ee47b64997f7dbc0d16b0f8bf440e76e61d810d82b79ff3295d46f07c051b8048076db67983fd8df940e78f69b30e5504a2e646590f429993dc97ef1be5dd
+  metadata.gz: '080d444267259e5323f40c2a43a95bac153e3a7aadf4f82e099500b92a43251ac4eb75bad2df1a3a6a50e45f70710bac5b3120d8b20a83db65679ed403189ba0'
+  data.tar.gz: 812e6fdffdbaffb41fa62c3d37ff146f115069e4710b3447d73046561274b19d86dd168edb9bcc34e30975f16aea489d49f65c19c1662581bb0e5bde6a9dfd6c

data/.rubocop.yml

@@ -9,3 +9,7 @@ AllCops:
 # Do not enforce documentation
 Style/Documentation:
   Enabled: false
+
+# Matching big hashes
+RSpec/ExampleLength:
+  Enabled: false

data/README.md

@@ -1,8 +1,6 @@
 # BlueprinterSchema
 
-### Create JSON Schema from [Blueprinter](https://github.com/procore-oss/blueprinter) Serializers and ActiveRecord Models.
-
-Serializers define which fields are used. Models know the database field types. Put these together and you get a JSON Schema.
+#### Create JSON Schemas from [Blueprinter](https://github.com/procore-oss/blueprinter) Serializers.
 
 ## Installation
 
@@ -14,33 +12,54 @@ gem "blueprinter_schema"
 
 ## Usage
 
-With the folloing Models and Serializers:
 ```rb
-class Address < ApplicationRecord
-  belongs_to :user
+class UserSerializer < Blueprinter::Base
+  field :first_name, type: [:string, :null]
+  field :last_name, type: [:string, :null]
+  field :full_name, type: [:string, :null], description: "The concatendated first and last name."
+  field :email, type: :string, format: :email
 end
 
-class User < ApplicationRecord
-  has_many :addresses
-end
+BlueprinterSchema.generate(serializer: UserSerializer)
+```
 
-class AddressSerializer < Blueprinter::Base
-  identifier :id
+```rb
+{
+  "type" => "object",
+  "properties" => {
+    "first_name" => {
+      "type" => ["string", "null"]
+    },
+    "last_name" => {
+      "type" => ["string", "null"]
+    },
+    "full_name" => {
+      "type" => ["string", "null"],
+      "description" => "The concatendated first and last name."
+    },
+    "email" => {
+      "type" => "string",
+      "format" => "email"
+    }
+  },
+  "required" => ["first_name", "last_name", "full_name", "email"],
+  "additionalProperties" => false
+}
+```
 
-  fields :address
-end
+You can pass an ActiveRecord Model to automatically infer types from DB fields:
 
+```rb
 class UserSerializer < Blueprinter::Base
-  identifier :id
+  field :first_name
+  field :last_name
+  field :email
+end
 
-  fields :name, :email, :created_at
-  association :addresses, blueprint: AddressSerializer
+class User < ApplicationRecord
 end
-```
 
-Generate JSON Schema:
-```rb
-BlueprinterSchema.generate(UserSerializer, User)
+BlueprinterSchema.generate(serializer: UserSerializer, model: User)
 ```
 
 ```rb
@@ -48,37 +67,74 @@ BlueprinterSchema.generate(UserSerializer, User)
   "type" => "object",
   "title" => "User",
   "properties" => {
-    "id" => {
-      "type" => "integer"
+    "first_name" => {
+      "type" => ["string", "null"]
     },
-    "created_at" => {
-      "type" => "string", "format" => "date-time"
+    "last_name" => {
+      "type" => ["string", "null"]
     },
     "email" => {
       "type" => "string"
-    },
-    "name" => {
-      "type" => ["string", "null"]
+    }
+  },
+  "required" => ["first_name", "last_name", "email"],
+  "additionalProperties" => false
+}
+```
+
+You can use associations:
+
+```rb
+class UserSerializer < Blueprinter::Base
+  field :email, type: :string
+
+  association :addresses, blueprint: AddressSerializer, collection: true
+  association :profile, blueprint: ProfileSerializer
+end
+
+class AddressSerializer < Blueprinter::Base
+  field :address, type: :string
+end
+
+class ProfileSerializer < Blueprinter::Base
+  field :public, type: :boolean
+end
+
+BlueprinterSchema.generate(serializer: UserSerializer)
+```
+
+```rb
+{
+  "type" => "object",
+  "properties" => {
+    "email" => {
+      "type" => "string"
     },
     "addresses" => {
       "type" => "array",
       "items" => {
         "type" => "object",
-        "title" => "Address",
         "properties" => {
-          "id" => {
-            "type" => "integer"
-          },
           "address" => {
             "type" => "string"
           }
         },
-        "required" => ["id", "address"],
+        "required" => ["address"],
         "additionalProperties" => false
       }
+    },
+    "profile" => {
+      "type" => "object",
+      "properties" => {
+        "public" => {
+          "type" => "boolean"
+        }
+      },
+      "required" => ["public"],
+      "additionalProperties" => false
     }
   },
-  "required" => ["id", "created_at", "email", "name"],
+  "required" => ["email", "addresses", "profile"],
   "additionalProperties" => false
 }
 ```
@@ -87,19 +143,30 @@ BlueprinterSchema.generate(UserSerializer, User)
 
 ```rb
 BlueprinterSchema.generate(
-  serializer,
-  model,
-  {
-    include_conditional_fields: true, # Whether or not to include conditional fields from the serializer
-    fallback_type: {}, # Type when no DB column is found or type is unknown. E.g. { 'type' => 'object' }
-    view: :default # The Blueprint view to use
-  }
+  serializer:,
+  model: nil,
+  include_conditional_fields: true, # Whether or not to include conditional fields from the serializer
+  fallback_type: {}, # Type when no DB column or type definition is found. E.g. { 'type' => 'object' }
+  view: :default # The blueprint view to use
 )
 ```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+Devcontainer / Codespaces / Native
+
+```sh
+bin/setup
+```
+
+Docker
+
+```sh
+docker compose up -d
+docker compose exec ruby bin/setup
+```
+
+Then, run `bundle exec rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 

data/Rakefile

@@ -1,12 +1,3 @@
 # frozen_string_literal: true
 
 require 'bundler/gem_tasks'
-require 'rspec/core/rake_task'
-
-RSpec::Core::RakeTask.new(:spec)
-
-require 'rubocop/rake_task'
-
-RuboCop::RakeTask.new
-
-task default: %i[spec rubocop]

data/lib/blueprinter_schema/generator.rb

@@ -1,31 +1,39 @@
 # frozen_string_literal: true
 
 module BlueprinterSchema
+  class InvalidJsonSchemaType < StandardError; end
+
+  # rubocop:disable Metrics/ClassLength
   class Generator
-    def initialize(serializer, model, options)
+    def initialize(serializer:, model:, skip_conditional_fields:, fallback_definition:, view:)
       @serializer = serializer
       @model = model
-      @options = options
+      @skip_conditional_fields = skip_conditional_fields
+      @fallback_definition = fallback_definition
+      @view = view
     end
 
     def generate
-      {
+      schema = {
         'type' => 'object',
-        'title' => @model.name,
         'properties' => build_properties,
         'required' => build_required_fields,
         'additionalProperties' => false
       }
+
+      schema['title'] = @model.name if @model
+
+      schema
     end
 
     private
 
     def fields
-      @fields ||= @serializer.reflections[@options[:view]].fields
+      @fields ||= @serializer.reflections[@view].fields
     end
 
     def associations
-      @associations ||= @serializer.reflections[@options[:view]].associations
+      @associations ||= @serializer.reflections[@view].associations
     end
 
     def build_properties
@@ -45,18 +53,41 @@ module BlueprinterSchema
     end
 
     def skip_field?(field)
-      !@options[:include_conditional_fields] &&
-        (field.options[:if] || field.options[:unless] || field.options[:exclude_if_nil])
+      @skip_conditional_fields && (field.options[:if] || field.options[:unless])
     end
 
     def build_required_fields
-      fields.reject { |_, field| skip_field?(field) }.keys.map(&:to_s)
+      fields
+        .reject { |_, field| field.options[:exclude_if_nil] }
+        .reject { |_, field| skip_field?(field) }
+        .keys.map(&:to_s)
     end
 
+    # rubocop:disable Metrics/AbcSize
     def field_to_json_schema(field)
-      column = @model.columns_hash[field.name.to_s]
+      type_definition = @fallback_definition.dup
+
+      if field.options[:type]
+        type_definition['type'] = ensure_valid_json_schema_types!(field)
+      elsif @model
+        column = @model.columns_hash[field.name.to_s]
+        type_definition = ar_column_to_json_schema(column)
+      end
+
+      type_definition['format'] = field.options[:format] if field.options[:format]
+      type_definition['description'] = field.options[:description] if field.options[:description]
+      type_definition
+    end
+    # rubocop:enable Metrics/AbcSize
+
+    def ensure_valid_json_schema_types!(field)
+      types = [field.options[:type]].flatten.map(&:to_s)
+
+      return field.options[:type] if types.all? do |type|
+        %w[string integer number boolean object array null].include?(type)
+      end
 
-      ar_column_to_json_schema(column) || @options[:fallback_type]
+      raise BlueprinterSchema::InvalidJsonSchemaType, "Invalid type: #{field.options[:type]}"
     end
 
     # rubocop:disable Metrics/MethodLength
@@ -93,13 +124,23 @@ module BlueprinterSchema
 
       return { 'type' => 'object' } unless blueprint_class
 
-      ar_association = @model.reflect_on_association(association.name)
-      is_collection = ar_association.collection?
-      association_model = ar_association.klass
+      ar_association = @model&.reflect_on_association(association.name)
+      is_collection = ar_association ? ar_association.collection? : association.options[:collection]
 
-      associated_schema = BlueprinterSchema.generate(blueprint_class, association_model)
+      associated_schema = recursive_generate(blueprint_class, ar_association&.klass)
 
       is_collection ? { 'type' => 'array', 'items' => associated_schema } : associated_schema
     end
+
+    def recursive_generate(serializer, model)
+      BlueprinterSchema.generate(
+        serializer:,
+        model:,
+        skip_conditional_fields: @skip_conditional_fields,
+        fallback_definition: @fallback_definition,
+        view: @view
+      )
+    end
   end
+  # rubocop:enable Metrics/ClassLength
 end

data/lib/blueprinter_schema/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BlueprinterSchema
-  VERSION = '0.5.0'
+  VERSION = '1.0.0'
 end

data/lib/blueprinter_schema.rb

@@ -4,7 +4,13 @@ require_relative 'blueprinter_schema/version'
 require_relative 'blueprinter_schema/generator'
 
 module BlueprinterSchema
-  def self.generate(serializer, model, options = { include_conditional_fields: true, fallback_type: {}, view: :default })
-    Generator.new(serializer, model, options).generate
+  def self.generate(
+    serializer:,
+    model: nil,
+    skip_conditional_fields: false,
+    fallback_definition: {},
+    view: :default
+  )
+    Generator.new(serializer:, model:, skip_conditional_fields:, fallback_definition:, view:).generate
   end
 end

metadata

@@ -1,14 +1,42 @@
 --- !ruby/object:Gem::Specification
 name: blueprinter_schema
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 1.0.0
 platform: ruby
 authors:
 - thisismydesign
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: blueprinter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 email:
 - git.thisismydesign@gmail.com
 executables: []