openapi_blocks 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 05d45b3316abff7109efe2f2438be8cb720300c67040c72a6c93245354b5129c
-  data.tar.gz: f51d879560afec23a90423ba83b162cb3c799748a4447e1b56e62a41a601dc9a
+  metadata.gz: c466c6845f12b5170db8082aab7e11146666fd06776e7026f29fb85ab2a9beb2
+  data.tar.gz: 99c38fe1681484456900b72ce75def577a248865d885abd21bf0d4b462ed27ad
 SHA512:
-  metadata.gz: c8c0ddcfde5053794e761fde4ecec89f5cbdcc021b37bd5dde751f76fdc6a0d05749802c9504bc05104c0c9fb242c533f3b94251f29961bf9c077fc4788850fd
-  data.tar.gz: 21a332227d4653fe2c233d666213087bc0e5ba91ef7210577f864d68a56987236d2023f2f7f9f5285dd5a9ea40b2eba97d1c1bf6d546ca7b0116fb897239f6c9
+  metadata.gz: 8f016873a16d2066461ae29891de560c5c4bd5867ec26a00fb99dbc9c4ca2c73887f9aefd64e272a5ed2c111f2a29b71756809ba19beba3fb8e3dde4c5bd7bb2
+  data.tar.gz: 70a4deb4c047856082593ada3c2c4476c5a5caf3aad08126d3505e35a233e8d12cc48ea49a95edfdc5ee47c70b870cfc0f87506f06a1e4dc31b1683e1f1df161

data/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-06-01
+
+### Added
+- Scalar UI served at `/docs/scalar` alongside Swagger UI
+- `SpecController#scalar` action serving Scalar with `displayRequestDuration` and Ruby `net_http` as default client
+ - `Resource` and `Controller` classes to support serializer-style resources and controller-scoped OpenAPI classes (`lib/openapi_blocks/resource.rb`, `lib/openapi_blocks/controller.rb`)
+
+### Changed
+- `OpenapiBlocks::Serializer` now uses `class_eval` to compile a monolithic extractor method per serializer class at boot time, eliminating per-object branching and lambda indirection
+- Field classification (model / virtual / association) computed once via `classify_fields` and memoized — no runtime `respond_to?` or `Array#include?` per object
+- Association metadata indexed by name in a `Hash` for O(1) lookup instead of `Array#find` per field per object
+- Association serializer classes resolved at compile time inside `build_assoc_method` instead of per-object via `Object.const_get`
+- Serializer is now **1.86× faster** than the original implementation and **3.6× faster** than `as_json` across 10–5000 records with consistent linear scaling
+ - `Builder#openapi_classes` expanded discovery to include classes ending with `Openapi` that inherit from `OpenapiBlocks::Base` or `OpenapiBlocks::Controller` (enables controller-scoped OpenAPI classes)
+ - `Serializer` now includes virtual attributes and associations marked `read_only` in serialized output (they previously were omitted). This ensures `read_only: true` fields are present in responses/listings while still being excluded from `*Input` schemas.
+ - `Base#infer_model` updated to strip both `Openapi` and `Resource` suffixes when inferring the model class name.
+
 ## [0.2.1] - 2026-06-01
 
 ### Changed

data/README.md

@@ -1,10 +1,21 @@
 # OpenapiBlocks
 
-OpenapiBlocks is a Rails gem that automatically generates OpenAPI 3.0/3.1 documentation from your ActiveRecord models, ActiveModel validations, and Rails routes — inspired by ActiveModel::Serializer (https://github.com/rails-api/active_model_serializers).
+OpenapiBlocks is a Rails gem that automatically generates OpenAPI 3.0/3.1 documentation from your ActiveRecord models, ActiveModel validations, and Rails routes — inspired by [ActiveModel::Serializer](https://github.com/rails-api/active_model_serializers).
 
 Versão em português brasileiro: README.pt-BR.md
 
-No manual annotation. No DSL noise in your controllers. Just declare what to expose and the spec is generated automatically.
+No manual annotation. No DSL noise in your controllers. Just declare what to expose and the spec is generated automatically. Includes a high-performance built-in serializer — ~3.6× faster than `as_json` with consistent linear scaling from 10 to 5000 records.
+
+## Key changes (recent)
+- `OpenapiBlocks::Resource` and `OpenapiBlocks::Controller` introduced as a cleaner alternative to `OpenapiBlocks::Base` — separating serialization from documentation concerns.
+- Default OpenAPI version is `3.1.0` (supported: `3.1.0`, `3.0.3`).
+- Scalar UI is now served at `/docs/scalar` alongside Swagger UI at `/docs`.
+- Swagger UI uses same-origin spec endpoints to avoid CORS issues.
+- YAML output is normalized to use string keys so Swagger UI accepts the `openapi` version field.
+- `association` DSL uses `read_only: true` to mark fields as response-only and exclude them from `*Input` schemas.
+- `tags` are generated at the document root from paths and can be customized via the `tags` DSL on classes and operations.
+- Schema references accept `Symbol` (e.g. `schema: :user`) and array items can be symbol references (e.g. `items: :user`).
+- Serializer uses `class_eval` to compile a monolithic extractor method per class at boot — eliminating per-object branching, lambda indirection, and runtime `respond_to?` checks.
 
 ---
 
@@ -40,7 +51,8 @@ end
 This exposes:
 
 ```
-GET /docs               ->  Swagger UI
+GET /docs               ->  Scalar UI
+GET /docs/swagger       ->  Swagger UI
 GET /docs/openapi.json  ->  OpenAPI spec in JSON
 GET /docs/openapi.yaml  ->  OpenAPI spec in YAML
 ```
@@ -50,7 +62,7 @@ GET /docs/openapi.yaml  ->  OpenAPI spec in YAML
 ```ruby
 # config/initializers/openapi_blocks.rb
 OpenapiBlocks.configure do |config|
-  config.openapi_version = "3.1"  # "3.0" or "3.1"
+  config.openapi_version = "3.1.0"  # "3.0.3" or "3.1.0"
 
   config.info do
     title       "My API"
@@ -95,77 +107,55 @@ end
 
 ## Usage
 
-### Creating an OpenAPI class
+OpenapiBlocks provides two base classes with distinct responsibilities:
+
+- `OpenapiBlocks::Resource` — defines the model, fields, associations, and serialization logic.
+- `OpenapiBlocks::Controller` — defines the API operations, parameters, and responses for documentation.
+- `OpenapiBlocks::Base` — legacy base class that combines both concerns. Still supported.
 
-Create a file in app/openapi/ following the same naming convention as ActiveModel::Serializer:
+### Resource + Controller (recommended)
 
 ```
 app/
   openapi/
-    user_openapi.rb     ->  User model
-    post_openapi.rb     ->  Post model
-    order_openapi.rb    ->  Order model
+    user_resource.rb    ->  serialization + schema
+    user_openapi.rb     ->  API documentation
+    post_resource.rb
+    post_openapi.rb
 ```
 
 ```ruby
-# app/openapi/user_openapi.rb
-class UserOpenapi < OpenapiBlocks::Base
+# app/openapi/user_resource.rb
+class UserResource < OpenapiBlocks::Resource
   # model User is inferred automatically from the class name
 
-  # custom tags (default: inferred from controller name)
-  tags "Users"
-
-  # opt-out sensitive or unnecessary fields
   ignore :password_digest, :reset_password_token
 
-  # opt-in associations
-  association :company
-  association :posts, type: :array, read_only: true  # excluded from UserInput
+  association :posts, type: :array, read_only: true
 
-  # virtual attributes (not in the database)
-  # read_only: true  ->  exposed in response (User), excluded from request body (UserInput)
-  # read_only: false ->  exposed in both User and UserInput
   attribute :full_name,    type: :string, read_only: true
   attribute :access_token, type: :string, read_only: true
   attribute :nickname,     type: :string
-end
-```
 
-### What is generated automatically
-
-Given this model:
+  # method defined here — called on the resource instance
+  def full_name
+    "#{object.name} (#{object.email})"
+  end
 
-```ruby
-class User < ApplicationRecord
-  validates :name,  presence: true, length: { minimum: 2, maximum: 100 }
-  validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
-  validates :age,   numericality: { greater_than: 0 }
-  validates :role,  inclusion: { in: %w[admin user guest] }
+  # or omit the method and it delegates to the model automatically
 end
 ```
 
-OpenapiBlocks generates:
-
-- User schema from db/schema.rb columns and types
-- UserInput schema for POST, PUT and PATCH request bodies (without id, created_at, updated_at and read_only virtual attributes)
-- required fields from presence: true validations
-- minLength, maxLength from length validations
-- minimum, maximum from numericality validations
-- enum from inclusion validations
-- format: "email" from format validations
-- All paths from config/routes.rb
-
-### Customizing operations
-
 ```ruby
 # app/openapi/user_openapi.rb
-class UserOpenapi < OpenapiBlocks::Base
+class UserOpenapi < OpenapiBlocks::Controller
+  resource UserResource
+
   tags "Users"
 
   operation :index do
     summary     "List all users"
     description "Returns a paginated list of active users"
-    tags        "Users", "Admin"  # overrides class-level tags for this operation
 
     parameter :page,     in: :query, type: :integer, description: "Page number"
     parameter :per_page, in: :query, type: :integer, description: "Items per page"
@@ -177,34 +167,111 @@ class UserOpenapi < OpenapiBlocks::Base
   operation :show do
     summary "Get a user"
 
-    response 200, description: "User found",     schema: :User
+    response 200, description: "User found", schema: :User
     response 404, description: "User not found"
+
+    no_security!
   end
+end
+```
 
-  operation :create do
-    summary "Create a user"
+```ruby
+# app/controllers/users_controller.rb
+def index
+  render json: UserResource.serialize(User.includes(:posts))
+end
 
-    response 201, description: "User created", schema: :User
-    response 422, description: "Invalid data"
-  end
+def show
+  render json: UserResource.serialize(User.find(params[:id]))
+end
+```
 
-  operation :update do
-    summary "Update a user"
+### Base (legacy, single class)
 
-    response 200, description: "User updated",   schema: :User
-    response 404, description: "User not found"
-    response 422, description: "Invalid data"
-  end
+```ruby
+# app/openapi/user_openapi.rb
+class UserOpenapi < OpenapiBlocks::Base
+  tags "Users"
 
-  operation :destroy do
-    summary "Delete a user"
+  ignore :password_digest
 
-    response 200, description: "User deleted"
-    response 404, description: "User not found"
+  association :posts, type: :array, read_only: true
+
+  attribute :full_name, type: :string, read_only: true
+
+  operation :index do
+    summary  "List all users"
+    response 200, description: "List of users", schema: { type: :array, items: :User }
   end
 end
 ```
 
+```ruby
+# app/controllers/users_controller.rb
+def index
+  render json: UserOpenapi.serialize(User.includes(:posts))
+end
+```
+
+---
+
+## Serializer
+
+The built-in serializer compiles a monolithic extractor method per class at boot time using `class_eval`. There are no loops, no lambda indirection, and no runtime branching per object.
+
+### Performance (200 records, arm64, Ruby 4.0)
+
+| | i/s | μs/i | vs serialize |
+|---|---|---|---|
+| serialize | 4 239 | 235 | — |
+| to_json | 1 444 | 692 | 2.94× slower |
+| as_json | 1 186 | 843 | 3.58× slower |
+| oj+as_json | 1 126 | 888 | 3.77× slower |
+
+Scaling is linear — the 3.6× advantage over `as_json` holds from 10 to 5000 records.
+
+### Virtual attributes and method resolution
+
+| Declared with | Method in resource? | Calls |
+|---|---|---|
+| `attribute :full_name` | yes | `resource_instance.full_name` |
+| `attribute :full_name` | no | `object.full_name` (delegated to model) |
+| column in db | — | `object.full_name` (direct) |
+
+### Association serializer resolution
+
+For each association, the serializer resolves the serializer class in this order:
+
+1. `PostResource` — has `serialize`, used directly.
+2. `PostOpenapi` — is a `Controller`, delegates to its `_resource`.
+3. Fallback — calls `as_json` on the association value.
+
+---
+
+## What is generated automatically
+
+Given this model:
+
+```ruby
+class User < ApplicationRecord
+  validates :name,  presence: true, length: { minimum: 2, maximum: 100 }
+  validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
+  validates :age,   numericality: { greater_than: 0 }
+  validates :role,  inclusion: { in: %w[admin user guest] }
+end
+```
+
+OpenapiBlocks generates:
+
+- `User` schema from `db/schema.rb` columns and types
+- `UserInput` schema for POST, PUT and PATCH request bodies (without `id`, `created_at`, `updated_at` and `read_only` fields)
+- `required` fields from `presence: true` validations
+- `minLength`, `maxLength` from `length` validations
+- `minimum`, `maximum` from `numericality` validations
+- `enum` from `inclusion` validations
+- `format: "email"` from format validations
+- All paths from `config/routes.rb`
+
 ---
 
 ## Security
@@ -235,9 +302,9 @@ end
 ## Associations
 
 ```ruby
-association :company                             # belongs_to — $ref to Company schema
-association :posts, type: :array                 # has_many — array of $ref to Post schema
-association :posts, type: :array, read_only: true   # excluded from UserInput (response only)
+association :company                                  # belongs_to — $ref to Company schema
+association :posts, type: :array                      # has_many — array of $ref to Post schema
+association :posts, type: :array, read_only: true     # excluded from UserInput (response only)
 ```
 
 ---
@@ -246,10 +313,10 @@ association :posts, type: :array, read_only: true   # excluded from UserInput (r
 
 Virtual attributes are fields that exist in the API response but not in the database.
 
-| Option           | Description                            | Appears in User | Appears in UserInput |
-| ---------------- | -------------------------------------- | :-------------: | :------------------: |
-| read_only: true  | Calculated or system-generated fields  |       YES       |          NO          |
-| read_only: false | Fields the client can send and receive |       YES       |         YES          |
+| Option | Description | Appears in User | Appears in UserInput |
+|---|---|:---:|:---:|
+| `read_only: true` | Calculated or system-generated fields | YES | NO |
+| `read_only: false` | Fields the client can send and receive | YES | YES |
 
 ```ruby
 attribute :full_name,    type: :string, read_only: true   # response only
@@ -261,19 +328,19 @@ attribute :nickname,     type: :string                    # request and response
 
 ## Type Mapping
 
-| ActiveRecord type | OpenAPI type       |
-| ----------------- | ------------------ |
-| integer           | integer / int32    |
-| bigint            | integer / int64    |
-| float             | number / float     |
-| decimal           | number / double    |
-| string            | string             |
-| text              | string             |
-| boolean           | boolean            |
-| date              | string / date      |
-| datetime          | string / date-time |
-| uuid              | string / uuid      |
-| json / jsonb      | object             |
+| ActiveRecord type | OpenAPI type |
+|---|---|
+| integer | integer / int32 |
+| bigint | integer / int64 |
+| float | number / float |
+| decimal | number / double |
+| string | string |
+| text | string |
+| boolean | boolean |
+| date | string / date |
+| datetime | string / date-time |
+| uuid | string / uuid |
+| json / jsonb | object |
 
 ---
 
@@ -288,7 +355,7 @@ config/routes.rb
 db/schema.rb
 ```
 
-The spec is automatically regenerated on the next request to /docs/openapi.json whenever any of these files change. No server restart needed.
+The spec is automatically regenerated on the next request to `/docs/openapi.json` whenever any of these files change. No server restart needed.
 
 ---
 
@@ -301,4 +368,4 @@ The spec is automatically regenerated on the next request to /docs/openapi.json
 
 ## License
 
-MIT (LICENSE.txt)
+MIT (LICENSE.txt)