jbuilder-schema 1.0.3 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 417f0269fa5ffbf0abc6f290e0d58195f6edcf6962b3b61b1df8f5776b4b11e3
-  data.tar.gz: f24925cd0c83dc407c40e8fd51a2168128957921f9487350f3bd9131442218ee
+  metadata.gz: 59f54a84c849a2b5575b89b9cfd959976d2fdd61224ccb12aad01a1bb2acfa2c
+  data.tar.gz: a927e3272a2dee69f3ead47da2d47470e99ff911a54cbde13f807f9ba32036ef
 SHA512:
-  metadata.gz: 61a6de749d11754e7997ee0a9162b4228d31d71acf43927fb5001797d563e0cc8b18434df09e419f19501a158f45d22c8f2b86727f1d0b47d79fcd4a7eea80c3
-  data.tar.gz: 11858924440856da7aa339f3cdb9e7ac8b4b4dfe9342939d202f0048982462c1a83a5c9b62ada301fe09f139c608d88ba9bcabe4635709c9499bfa05a3908246
+  metadata.gz: 035745d04230e753d8df7a1811c139b9ab5b49eb7c3d7606485a086208c0150c9b4123ecc52d3f69a41432af497dc3973cd70db3f0b722e5162c0147f84a3289
+  data.tar.gz: 20f2caceef04841ce35529b00bfac43a7aa29518102626a76f5d61763a72b0dffa04756f80fe2167592a7e91534c0e65efb17e315bd57aa117d43f80751eb018

data/Gemfile

@@ -7,8 +7,7 @@ gemspec
 
 gem "rake", "~> 13.0"
 
-gem "factory_bot"
-gem "faker"
+gem "sqlite3"
 
 gem "standard", "~> 1.3"
 

data/Gemfile.lock

@@ -1,75 +1,74 @@
 PATH
   remote: .
   specs:
-    jbuilder-schema (1.0.3)
+    jbuilder-schema (2.0.0)
       jbuilder
       rails (>= 5.0.0)
-      safe_parser
 
 GEM
   remote: https://rubygems.org/
   specs:
-    actioncable (7.0.3.1)
-      actionpack (= 7.0.3.1)
-      activesupport (= 7.0.3.1)
+    actioncable (7.0.4)
+      actionpack (= 7.0.4)
+      activesupport (= 7.0.4)
       nio4r (~> 2.0)
       websocket-driver (>= 0.6.1)
-    actionmailbox (7.0.3.1)
-      actionpack (= 7.0.3.1)
-      activejob (= 7.0.3.1)
-      activerecord (= 7.0.3.1)
-      activestorage (= 7.0.3.1)
-      activesupport (= 7.0.3.1)
+    actionmailbox (7.0.4)
+      actionpack (= 7.0.4)
+      activejob (= 7.0.4)
+      activerecord (= 7.0.4)
+      activestorage (= 7.0.4)
+      activesupport (= 7.0.4)
       mail (>= 2.7.1)
       net-imap
       net-pop
       net-smtp
-    actionmailer (7.0.3.1)
-      actionpack (= 7.0.3.1)
-      actionview (= 7.0.3.1)
-      activejob (= 7.0.3.1)
-      activesupport (= 7.0.3.1)
+    actionmailer (7.0.4)
+      actionpack (= 7.0.4)
+      actionview (= 7.0.4)
+      activejob (= 7.0.4)
+      activesupport (= 7.0.4)
       mail (~> 2.5, >= 2.5.4)
       net-imap
       net-pop
       net-smtp
       rails-dom-testing (~> 2.0)
-    actionpack (7.0.3.1)
-      actionview (= 7.0.3.1)
-      activesupport (= 7.0.3.1)
+    actionpack (7.0.4)
+      actionview (= 7.0.4)
+      activesupport (= 7.0.4)
       rack (~> 2.0, >= 2.2.0)
       rack-test (>= 0.6.3)
       rails-dom-testing (~> 2.0)
       rails-html-sanitizer (~> 1.0, >= 1.2.0)
-    actiontext (7.0.3.1)
-      actionpack (= 7.0.3.1)
-      activerecord (= 7.0.3.1)
-      activestorage (= 7.0.3.1)
-      activesupport (= 7.0.3.1)
+    actiontext (7.0.4)
+      actionpack (= 7.0.4)
+      activerecord (= 7.0.4)
+      activestorage (= 7.0.4)
+      activesupport (= 7.0.4)
       globalid (>= 0.6.0)
       nokogiri (>= 1.8.5)
-    actionview (7.0.3.1)
-      activesupport (= 7.0.3.1)
+    actionview (7.0.4)
+      activesupport (= 7.0.4)
       builder (~> 3.1)
       erubi (~> 1.4)
       rails-dom-testing (~> 2.0)
       rails-html-sanitizer (~> 1.1, >= 1.2.0)
-    activejob (7.0.3.1)
-      activesupport (= 7.0.3.1)
+    activejob (7.0.4)
+      activesupport (= 7.0.4)
       globalid (>= 0.3.6)
-    activemodel (7.0.3.1)
-      activesupport (= 7.0.3.1)
-    activerecord (7.0.3.1)
-      activemodel (= 7.0.3.1)
-      activesupport (= 7.0.3.1)
-    activestorage (7.0.3.1)
-      actionpack (= 7.0.3.1)
-      activejob (= 7.0.3.1)
-      activerecord (= 7.0.3.1)
-      activesupport (= 7.0.3.1)
+    activemodel (7.0.4)
+      activesupport (= 7.0.4)
+    activerecord (7.0.4)
+      activemodel (= 7.0.4)
+      activesupport (= 7.0.4)
+    activestorage (7.0.4)
+      actionpack (= 7.0.4)
+      activejob (= 7.0.4)
+      activerecord (= 7.0.4)
+      activesupport (= 7.0.4)
       marcel (~> 1.0)
       mini_mime (>= 1.1.0)
-    activesupport (7.0.3.1)
+    activesupport (7.0.4)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 1.6, < 2)
       minitest (>= 5.1)
@@ -79,10 +78,6 @@ GEM
     concurrent-ruby (1.1.10)
     crass (1.0.6)
     erubi (1.11.0)
-    factory_bot (6.2.1)
-      activesupport (>= 5.0.0)
-    faker (2.22.0)
-      i18n (>= 1.8.11, < 2)
     globalid (1.0.0)
       activesupport (>= 5.0)
     i18n (1.12.0)
@@ -100,7 +95,7 @@ GEM
     method_source (1.0.0)
     mini_mime (1.1.2)
     mini_portile2 (2.8.0)
-    minitest (5.16.2)
+    minitest (5.16.3)
     mocha (1.14.0)
     net-imap (0.3.1)
       net-protocol
@@ -108,10 +103,10 @@ GEM
       net-protocol
     net-protocol (0.1.3)
       timeout
-    net-smtp (0.3.2)
+    net-smtp (0.3.3)
       net-protocol
     nio4r (2.5.8)
-    nokogiri (1.13.8)
+    nokogiri (1.13.9)
       mini_portile2 (~> 2.8.0)
       racc (~> 1.4)
     parallel (1.22.1)
@@ -121,28 +116,28 @@ GEM
     rack (2.2.4)
     rack-test (2.0.2)
       rack (>= 1.3)
-    rails (7.0.3.1)
-      actioncable (= 7.0.3.1)
-      actionmailbox (= 7.0.3.1)
-      actionmailer (= 7.0.3.1)
-      actionpack (= 7.0.3.1)
-      actiontext (= 7.0.3.1)
-      actionview (= 7.0.3.1)
-      activejob (= 7.0.3.1)
-      activemodel (= 7.0.3.1)
-      activerecord (= 7.0.3.1)
-      activestorage (= 7.0.3.1)
-      activesupport (= 7.0.3.1)
+    rails (7.0.4)
+      actioncable (= 7.0.4)
+      actionmailbox (= 7.0.4)
+      actionmailer (= 7.0.4)
+      actionpack (= 7.0.4)
+      actiontext (= 7.0.4)
+      actionview (= 7.0.4)
+      activejob (= 7.0.4)
+      activemodel (= 7.0.4)
+      activerecord (= 7.0.4)
+      activestorage (= 7.0.4)
+      activesupport (= 7.0.4)
       bundler (>= 1.15.0)
-      railties (= 7.0.3.1)
+      railties (= 7.0.4)
     rails-dom-testing (2.0.3)
       activesupport (>= 4.2.0)
       nokogiri (>= 1.6)
     rails-html-sanitizer (1.4.3)
       loofah (~> 2.3)
-    railties (7.0.3.1)
-      actionpack (= 7.0.3.1)
-      activesupport (= 7.0.3.1)
+    railties (7.0.4)
+      actionpack (= 7.0.4)
+      activesupport (= 7.0.4)
       method_source
       rake (>= 12.2)
       thor (~> 1.0)
@@ -167,11 +162,8 @@ GEM
       rubocop (>= 1.7.0, < 2.0)
       rubocop-ast (>= 0.4.0)
     ruby-progressbar (1.11.0)
-    ruby_parser (3.8.4)
-      sexp_processor (~> 4.1)
-    safe_parser (1.0.0)
-      ruby_parser (~> 3.8.4)
-    sexp_processor (4.16.1)
+    sqlite3 (1.5.3)
+      mini_portile2 (~> 2.8.0)
     standard (1.14.0)
       rubocop (= 1.32.0)
       rubocop-performance (= 1.14.3)
@@ -183,17 +175,16 @@ GEM
     websocket-driver (0.7.5)
       websocket-extensions (>= 0.1.0)
     websocket-extensions (0.1.5)
-    zeitwerk (2.6.1)
+    zeitwerk (2.6.6)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  factory_bot
-  faker
   jbuilder-schema!
   mocha
   rake (~> 13.0)
+  sqlite3
   standard (~> 1.3)
 
 BUNDLED WITH

data/README.md

@@ -1,4 +1,4 @@
-# JbuilderSchema
+# Jbuilder::Schema
 
 Generate JSON Schema compatible with OpenAPI 3 specs from Jbuilder files
 
@@ -7,12 +7,12 @@ Generate JSON Schema compatible with OpenAPI 3 specs from Jbuilder files
 
 ## Installation
 
-In Gemfile put `gem "jbuilder-schema"` **before** `gem "jbuilder"`:
+In your Gemfile, put `gem "jbuilder-schema"` after Jbuilder:
 
-    gem "jbuilder-schema", require: "jbuilder/schema"
     gem "jbuilder"
+    gem "jbuilder-schema"
 
-And then execute:
+And run:
 
     $ bundle
 
@@ -22,114 +22,142 @@ Or install it yourself as:
 
 ## Usage
 
-Wherever you want to generate schemas, you should extend `JbuilderSchema`:
+Wherever you want to generate schemas, call `Jbuilder::Schema.yaml` or `Jbuilder::Schema.json`:
 
-    extend JbuilderSchema
+```ruby
+Jbuilder::Schema.yaml(@article, title: 'Article', description: 'Article in the blog', locals: { current_user: @user })
+```
 
-Then you can use `jbuilder_schema` helper:
+Under the hood `Jbuilder::Schema.yaml`/`json` will use Action View's `render` method and support the same arguments.
 
-    jbuilder_schema('api/v1/articles/_article',
-                    title: 'Article',
-                    description: 'Article in the blog',
-                    format: :yaml,
-                    paths: view_paths.map(&:path),
-                    model: Article,
-                    locals: {
-                      article: @article,
-                      current_user: @user
-                    })
+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.
 
-`jbuilder_schema` helper takes `path` to Jbuilder template as a first argument and several optional arguments:
+Additionally, we can pass any needed `locals:`.
 
-- `title` and `description`: Title and description of schema, if not passed then they will be grabbed from locale files (see *[Titles & Descriptions](#titles--descriptions)*);
-- `format`: Desired output format, can be either `:yaml` or `:json`. If no `format` option is passed, the output will be the Ruby Hash object;
-- `paths`: If you need to scope any other paths than `app/views`, pass them as an array here;
-- `model`: Model described in template, this is needed to populate `required` field in schema;
-- `locals`: Here you should pass all the locals which are met in the jbuilder template. Those could be any objects as long as they respond to methods called on them in template.
+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)*);
 
-Notice that partial templates should be prepended with an underscore just like in the name of the file (i.e. `_article` but not `article` an when using Jbuilder).
+### Use with a directory within app/views
+
+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:
+
+```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:
+
+```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:
+
+```ruby
+Jbuilder::Schema.yaml(template: "articles/index", assigns: { articles: Article.first(3) })
+```
 
 ### Output
 
-JbuilderSchema automatically sets `description`, `type`, and `required` options in JSON-Schema.
+Jbuilder::Schema automatically sets `description`, `type`, and `required` options in JSON-Schema.
 
-For example, if we have `_articles.json.jbilder` file:
+For example, if we have a `_article.json.jbuilder` file:
 
-    json.extract! article, :id, :title, :body, :created_at
+```ruby
+json.extract! article, :id, :title, :body, :created_at
+```
 
-The output for it will be:
+This will produce the following:
 
-    type: object
-    title: Article
-    description: Article in the blog
-    required:
-      - id
-      - title
-      - body
-    properties:
-      id:
-        description: ID of an article
-        type: integer
-      title:
-        description: Title of an article
-        type: string
-      body:
-        description: Contents of an article
-        type: string
-      created_at:
-        description: Timestamp when article was created
-        type: string
-        format: date-time
+```yaml
+type: object
+title: Article
+description: Article in the blog
+required:
+  - id
+  - title
+  - body
+properties:
+  id:
+    description: ID of an article
+    type: integer
+  title:
+    description: Title of an article
+    type: string
+  body:
+    description: Contents of an article
+    type: string
+  created_at:
+    description: Timestamp when article was created
+    type: string
+    format: date-time
+```
 
 ### Customization
 
 #### Simple
 
-Sometimes you would want to set you own data in generated JSON-Schema. All you need to do is just pass hash with it under `schema` keyword in your jbuilder template:
+To set your own data in the generated JSON-Schema pass a `schema:` hash:
 
-    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}$/ }
+```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}$/ }
+```
 
 This will produce the following:
 
-    ...
-      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}$"
+```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}$"
+```
 
 #### Bulk
 
 You can customize output for multiple fields at once:
 
-    json.extract! user, :id, :name, :email, schema: {id: {type: :string}, email: {type: :email, pattern: /^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$/}}
+```ruby
+json.extract! user, :id, :name, :email, schema: {id: {type: :string}, email: {type: :email, pattern: /^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$/}}
+```
 
 ### Nested objects
 
-When you have nested objects in jbuilder template, you have to pass it to `schema: {object: <nested_object>}` when the block starts:
+When you have nested objects in your Jbuilder template, you have to pass it to `schema: {object: <nested_object>}` when the block starts:
 
-    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
-    end
+```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
+end
+```
 
-This will help JbuilderSchema to process those fields right.
+This will help Jbuilder::Schema to process those fields right.
 
 ### Collections
 
@@ -137,24 +165,28 @@ If an object or an array of objects is generated in template, either in root or
 
 For example, if we have:
 
-    json.user do
-      json.partial! 'api/v1/users/user', user: user
-    end
+```ruby
+json.user do
+  json.partial! 'api/v1/users/user', user: user
+end
 
-    json.articles do
-      json.array! user.articles, partial: "api/v1/articles/article", as: :article
-    end
+json.articles do
+  json.array! user.articles, partial: "api/v1/articles/article", as: :article
+end
+```
 
 The result would be:
 
-    user:
-      type: object
-      $ref: #/components/schemas/user
-    articles:
-      type: array
-      items:
-        $ref: #/components/schemas/article
-    
+```yaml
+user:
+  type: object
+  $ref: #/components/schemas/user
+articles:
+  type: array
+  items:
+    $ref: #/components/schemas/article
+```
+
 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
@@ -163,63 +195,57 @@ Custom titles and descriptions for objects can be specified when calling `jbuild
 
 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:
 
-    en:
-      articles:
-        title: Article
-        description: The main object on the blog
+```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:
 
-    en:
-      articles:
-        fields:
-          title:
-            description: The title of an article
+```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 JbuilderSchema uses (for example, in `config/initializers/jbuilder_schema.rb`):
+You can configure some variables that Jbuilder::Schema uses (for example, in `config/initializers/jbuilder_schema.rb`):
 
-    JbuilderSchema.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"
-    end
+```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"
+end
+```
 
 ### RSwag
 
-It's super easy to use JbuilderSchema with RSwag: just add `jbuilder_schema` helper in `swagger_helper.rb` like this:
-
-    RSpec.configure do |config|
-      extend JbuilderSchema
-
-      ...
-
-      config.swagger_docs = {
-
-        ...
-      
-        components: {
-          schemas: {
-            article: jbuilder_schema('api/v1/articles/_article',
-                                     format: :yaml,
-                                     model: Article,
-                                     title: 'Article',
-                                     description: 'Article in the blog',
-                                     locals: {
-                                       article: FactoryBot.build(:article, id: 1),
-                                       current_user: FactoryBot.build(:user, admin: true)
-                                     })
-          }
-        }
-
-        ...
-
+You can use the `yaml`/`json` methods in your `swagger_helper.rb` like this:
+
+```ruby
+RSpec.configure do |config|
+  config.swagger_docs = {
+    components: {
+      schemas: {
+        article: Jbuilder::Schema.yaml(FactoryBot.build(:article, id: 1),
+          title: 'Article',
+          description: 'Article in the blog',
+          locals: {
+            current_user: FactoryBot.build(:user, admin: true)
+          })
       }
-
-      ...
+    }
+  }
+end
+```
 
 ## Contributing