openapi_blocks 0.3.1 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a45ac9389f6202430fb9c21ded74a327d221a9925e5b6a9a3622ea712a216290
-  data.tar.gz: bc02bd7c04f7ab2e2c6981b23ca317c500b070bfddb4120808d1b801d300c679
+  metadata.gz: eafa1f0685d4c659609b5116dfac6e7204cee4bd5c60ea882417aebbe4cd67dd
+  data.tar.gz: db613ff23df3f705b70f126f02a0d03334fffe8a8fcbfd3dbe563343fce69ef8
 SHA512:
-  metadata.gz: 28ab89af18ab105d20c37ea9882239925d2afba4a8f644fb038d1d93c444fc29b94f4f117429a36e0d6442116fe984c48bafbb37fbef0ebd4131a994e2d04141
-  data.tar.gz: a679b294432e62db66c3e3e774d042319aaf4d9371a3e788bcbcedecc3f71906a7b924b04090196c79a608a177a245fb12f545ad272307882e3d3ed459079f67
+  metadata.gz: f88f54dcc99be63820da03cedaa9062d5e1c3e185c1cbf0d6aa3ac2c00f066b9ea75002dd1e8d4061f51c0f4bb71d606dc5b632de4f80870f3c598bd47312ef7
+  data.tar.gz: 75027794cbdebde235211302cc5da8495f2dba128441cdd8d94bfea4d7808acd1a66ef40569f768698c5c2b32fba205f99c71305673105b0229276d4c9c9e505

data/CHANGELOG.md

@@ -7,31 +7,68 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-06-02
+
+- Change parallel version
+
+## [0.4.0] - 2026-06-02
+
+### Added
+
+- `OpenapiBlocks::Serializer` base class for standalone serializers in `app/serializers/` — infers model from class name (e.g. `UserSerializer` -> `User`)
+- `OpenapiBlocks::Concerns::Schemable` module extracted from `Base` — provides `model`, `ignore`, `association`, `attribute`, `serializes` DSL
+- `OpenapiBlocks::Concerns::Documentable` module extracted from `Base` — provides `operation`, `tags` DSL
+- `OpenapiBlocks::Serialization` module — internal serialization engine shared by `Base` and `Serializer`
+- `OpenapiBlocks::Registry` — maps models to serializers at boot; supports convention-based (`UserSerializer` -> `User`) and explicit (`serializes User`) registration
+- `OpenapiBlocks::AutoSerialize` — Rack middleware that intercepts `render json:` calls and applies the registered serializer automatically when `config.auto_serialize = true`
+- `Configuration#auto_serialize` flag — opt-in automatic serialization via `config.auto_serialize = true`
+- `Configuration#configured?` flag — set to `true` when `config.info` block is called
+- `Builder#validate_configuration!` — raises `OpenapiBlocks::Error` with a descriptive message if `configure` was never called or `info.title`/`info.version` are blank
+- `Railtie` now eager loads `app/serializers/**/*.rb` alongside `app/openapi/**/*.rb`
+- `Railtie` builds `Registry` and injects `AutoSerialize` into `ActionController::Base` and `ActionController::API` when `auto_serialize` is enabled
+
+### Changed
+
+- `OpenapiBlocks::Resource` removed — replaced by `OpenapiBlocks::Serializer`
+- `OpenapiBlocks::Serialization` hierarchy traversal stops at `serialization_sentinel` instead of hardcoded `OpenapiBlocks::Base`
+- `resolve_assoc_serializer` lookup order: `PostSerializer` -> `PostOpenapi` (delegates to `_resource` if Controller) -> fallback to `as_json`
+- `Spec::Components#build` resolves model via `resolve_schema_klass` — supports both `Controller` (via `_resource`) and `Serializer` as schema source
+- `Base` now includes `Concerns::Schemable` and `Concerns::Documentable` — no behavioral change for existing users
+- Supported `openapi_version` values changed to `"3.1.0"` and `"3.0.3"` (previously `"3.1"` and `"3.0"`)
+
+### Removed
+
+- `lib/openapi_blocks/resource.rb` — `OpenapiBlocks::Resource` is no longer part of the public API
+
 ## [0.3.1] - 2026-06-02
 
 ### Changed
+
 - `OpenapiBlocks::Controller` now uses `controller` to specifies exact controller
 
 ## [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`)
+- `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.
+- `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
+
 - `association` DSL now uses `read_only: true` instead of `input: false` for consistency with `attribute` DSL
 
 ## [0.2.0] - 2026-06-01

data/README.md

@@ -2,26 +2,15 @@
 
 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
+Versão em português brasileiro: [README.pt-BR.md](README.pt-BR.md)
 
 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.
-
 ---
 
 ## Installation
 
-Add to your Gemfile:
+Add to your `Gemfile`:
 
 ```ruby
 gem "openapi_blocks"
@@ -51,7 +40,7 @@ end
 This exposes:
 
 ```
-GET /docs               ->  Scalar UI
+GET /docs               ->  Scalar UI (default)
 GET /docs/swagger       ->  Swagger UI
 GET /docs/openapi.json  ->  OpenAPI spec in JSON
 GET /docs/openapi.yaml  ->  OpenAPI spec in YAML
@@ -59,14 +48,16 @@ GET /docs/openapi.yaml  ->  OpenAPI spec in YAML
 
 ### 2. Configure the initializer
 
+`OpenapiBlocks.configure` is required. The gem raises `OpenapiBlocks::Error` on the first request if it was never called or if `info.title` / `info.version` are blank.
+
 ```ruby
 # config/initializers/openapi_blocks.rb
 OpenapiBlocks.configure do |config|
-  config.openapi_version = "3.1.0"  # "3.0.3" or "3.1.0"
+  config.openapi_version = "3.1.0"  # required — "3.0.3" or "3.1.0"
 
   config.info do
-    title       "My API"
-    version     "1.0.0"
+    title       "My API"    # required
+    version     "1.0.0"     # required
     description "API documentation generated automatically"
 
     contact do
@@ -93,7 +84,8 @@ OpenapiBlocks.configure do |config|
     end
   end
 
-  config.watch = :development  # auto-reload on file changes
+  config.watch          = :development  # auto-reload on file changes
+  config.auto_serialize = true          # optional — see Auto Serialization below
 
   # optional: security schemes
   config.security do
@@ -109,24 +101,25 @@ end
 
 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::Serializer` — defines the model, fields, associations, and serialization logic. Lives in `app/serializers/`.
+- `OpenapiBlocks::Controller` — defines API operations, parameters, and responses for documentation. Lives in `app/openapi/`.
 - `OpenapiBlocks::Base` — legacy base class that combines both concerns. Still supported.
 
-### Resource + Controller (recommended)
+### Recommended: Serializer + Controller
 
 ```
 app/
+  serializers/
+    user_serializer.rb    ->  serialization + schema
+    post_serializer.rb
   openapi/
-    user_resource.rb    ->  serialization + schema
-    user_openapi.rb     ->  API documentation
-    post_resource.rb
+    user_openapi.rb       ->  API documentation
     post_openapi.rb
 ```
 
 ```ruby
-# app/openapi/user_resource.rb
-class UserResource < OpenapiBlocks::Resource
+# app/serializers/user_serializer.rb
+class UserSerializer < OpenapiBlocks::Serializer
   # model User is inferred automatically from the class name
 
   ignore :password_digest, :reset_password_token
@@ -137,7 +130,7 @@ class UserResource < OpenapiBlocks::Resource
   attribute :access_token, type: :string, read_only: true
   attribute :nickname,     type: :string
 
-  # method defined here — called on the resource instance
+  # method defined here — called on the serializer instance
   def full_name
     "#{object.name} (#{object.email})"
   end
@@ -149,7 +142,7 @@ end
 ```ruby
 # app/openapi/user_openapi.rb
 class UserOpenapi < OpenapiBlocks::Controller
-  resource UserResource
+  resource   UserSerializer
   controller UsersController
 
   tags "Users"
@@ -179,15 +172,15 @@ end
 ```ruby
 # app/controllers/users_controller.rb
 def index
-  render json: UserResource.serialize(User.includes(:posts))
+  render json: UserSerializer.serialize(User.includes(:posts))
 end
 
 def show
-  render json: UserResource.serialize(User.find(params[:id]))
+  render json: UserSerializer.serialize(User.find(params[:id]))
 end
 ```
 
-### Base (legacy, single class)
+### Legacy: Base (single class)
 
 ```ruby
 # app/openapi/user_openapi.rb
@@ -216,35 +209,67 @@ end
 
 ---
 
+## Auto Serialization
+
+When `config.auto_serialize = true`, OpenapiBlocks intercepts every `render json:` call and automatically applies the registered serializer — no explicit serializer call needed in controllers.
+
+```ruby
+# config/initializers/openapi_blocks.rb
+config.auto_serialize = true
+```
+
+```ruby
+# app/controllers/users_controller.rb
+def index
+  render json: User.all  # automatically serialized by UserSerializer
+end
+
+def show
+  render json: @user  # automatically serialized by UserSerializer
+end
+```
+
+Serializer registration is automatic by convention (`UserSerializer` -> `User`). For explicit registration:
+
+```ruby
+class AdminUserSerializer < OpenapiBlocks::Serializer
+  serializes User  # explicitly maps this serializer to the User model
+end
+```
+
+If no serializer is found, OpenapiBlocks falls back to default Rails rendering and logs a warning.
+
+---
+
 ## 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 |
+| Method     | 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) |
+| Declared with          | Method in serializer? | Calls                                   |
+| ---------------------- | --------------------- | --------------------------------------- |
+| `attribute :full_name` | yes                   | `serializer_instance.full_name`         |
+| `attribute :full_name` | no                    | `object.full_name` (delegated to model) |
+| column in db           | —                     | `object.attribute` (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`.
+1. `PostSerializer` — has `serialize`, used directly.
+2. `PostOpenapi` — is a `Controller`, delegates to its `resource`.
 3. Fallback — calls `as_json` on the association value.
 
 ---
@@ -265,7 +290,7 @@ 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)
+- `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
@@ -281,8 +306,8 @@ Configure global security schemes in the initializer:
 
 ```ruby
 config.security do
-  bearer_token format: "JWT"                    # Authorization: Bearer <token>
-  api_key      name: "X-API-Key", in: :header   # X-API-Key: <key>
+  bearer_token format: "JWT"                   # Authorization: Bearer <token>
+  api_key      name: "X-API-Key", in: :header  # X-API-Key: <key>
 end
 ```
 
@@ -290,11 +315,11 @@ Override security per operation:
 
 ```ruby
 operation :index do
-  security :bearerAuth   # only bearer on this operation
+  security :bearerAuth  # only bearer on this operation
 end
 
 operation :show do
-  no_security!           # public endpoint — no auth required
+  no_security!          # public endpoint — no auth required
 end
 ```
 
@@ -303,9 +328,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)
 ```
 
 ---
@@ -314,34 +339,34 @@ association :posts, type: :array, read_only: true     # excluded from UserInput
 
 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
-attribute :access_token, type: :string, read_only: true   # response only
-attribute :nickname,     type: :string                    # request and response
+attribute :full_name,    type: :string, read_only: true  # response only
+attribute :access_token, type: :string, read_only: true  # response only
+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`               |
 
 ---
 
@@ -350,6 +375,7 @@ attribute :nickname,     type: :string                    # request and response
 OpenapiBlocks watches for changes in:
 
 ```
+app/serializers/**/*.rb
 app/openapi/**/*.rb
 app/models/**/*.rb
 config/routes.rb
@@ -369,4 +395,4 @@ The spec is automatically regenerated on the next request to `/docs/openapi.json
 
 ## License
 
-MIT (LICENSE.txt)
+[MIT](LICENSE.txt)