openapi_blocks 0.3.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a45ac9389f6202430fb9c21ded74a327d221a9925e5b6a9a3622ea712a216290
-  data.tar.gz: bc02bd7c04f7ab2e2c6981b23ca317c500b070bfddb4120808d1b801d300c679
+  metadata.gz: a555c50cffdc3d57e766d1d644a2a7715ac4ab3ad730484169f86b09538d9da9
+  data.tar.gz: e55fe98e2c802e9823bef23683a8b431e97ecda4d7f6781d02995a7f5d9d1da7
 SHA512:
-  metadata.gz: 28ab89af18ab105d20c37ea9882239925d2afba4a8f644fb038d1d93c444fc29b94f4f117429a36e0d6442116fe984c48bafbb37fbef0ebd4131a994e2d04141
-  data.tar.gz: a679b294432e62db66c3e3e774d042319aaf4d9371a3e788bcbcedecc3f71906a7b924b04090196c79a608a177a245fb12f545ad272307882e3d3ed459079f67
+  metadata.gz: 223d4851ce536c0d9cc685e5098bfe6bb3dbb9cd278ecf7f28287eab0aa6ed58fc06ecad9b1ee470f55a10843256c4e89f6c1ce298d5effadc3140597cdc375a
+  data.tar.gz: 65d27cbd44d7f8555d9fe9ad6fdf147f25e0d7e888411ba3aeef7db80ff085799d8c25d4a4dfebbfd33f0285bb3695c00af12c793609b3018f893b233e4f164d

data/CHANGELOG.md

@@ -7,31 +7,72 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-06-02
+
+- Added generators
+
+## [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

@@ -1,21 +1,10 @@
 # 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. 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.
+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.
 
 ---
 
@@ -35,6 +24,70 @@ bundle install
 
 ---
 
+## Generators
+
+OpenapiBlocks provides three generators to get you started quickly.
+
+### Install
+
+```bash
+rails generate openapi_blocks:install
+```
+
+Creates `config/initializers/openapi_blocks.rb` with all available options commented out, and mounts the engine in `config/routes.rb`:
+
+```ruby
+mount OpenapiBlocks::Engine => "/docs"
+```
+
+### Openapi
+
+```bash
+rails generate openapi_blocks:openapi User
+```
+
+Creates `app/openapi/user_openapi.rb` with all available DSL options commented out:
+
+```ruby
+# app/openapi/user_openapi.rb
+class UserOpenapi < OpenapiBlocks::Controller
+  # resource UserSerializer
+  # controller UsersController
+
+  # tags "Users"
+
+  # operation :index do
+  #   summary     "List all users"
+  #   response 200, description: "List of users", schema: { type: :array, items: :User }
+  # end
+end
+```
+
+### Serializer
+
+```bash
+rails generate openapi_blocks:serializer User
+```
+
+Creates `app/serializers/user_serializer.rb` with all available DSL options commented out:
+
+```ruby
+# app/serializers/user_serializer.rb
+class UserSerializer < OpenapiBlocks::Serializer
+  # ignore :password_digest, :reset_password_token
+
+  # association :posts, type: :array, read_only: true
+  # association :company
+
+  # attribute :full_name, type: :string, read_only: true
+  # def full_name
+  #   "#{object.first_name} #{object.last_name}"
+  # end
+end
+```
+
+---
+
 ## Setup
 
 ### 1. Mount the Engine
@@ -51,7 +104,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 +112,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 +148,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 +165,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::Base` — legacy base class that combines both concerns. Still supported.
+- 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 +194,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 +206,7 @@ end
 ```ruby
 # app/openapi/user_openapi.rb
 class UserOpenapi < OpenapiBlocks::Controller
-  resource UserResource
+  resource   UserSerializer  # links to the serializer — schema is derived from it
   controller UsersController
 
   tags "Users"
@@ -176,18 +233,31 @@ class UserOpenapi < OpenapiBlocks::Controller
 end
 ```
 
+#### How the OpenAPI schema is generated
+
+When `resource UserSerializer` is declared in a `Controller`, OpenapiBlocks derives the OpenAPI schema directly from the serializer — not from the model. This guarantees that what is documented is exactly what the API returns.
+
+The schema is built from three sources on the serializer:
+
+- ActiveRecord columns — read from `db/schema.rb` via the inferred model. Column types are mapped to OpenAPI types automatically.
+- `attribute` declarations — virtual fields not present in the database. Fields declared with `read_only: true` appear in the `User` response schema but are excluded from the `UserInput` request schema.
+- `association` declarations — resolved as `$ref` to the associated schema. Associations declared with `read_only: true` appear in the response but are excluded from `UserInput`.
+- `ignore` declarations — columns excluded from both schemas.
+
+The `UserInput` schema (used in POST, PUT and PATCH request bodies) is derived automatically from the `User` schema by removing `id`, `created_at`, `updated_at`, and any field marked `read_only: true`.
+
 ```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,36 +286,68 @@ 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.
+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   | us/i | vs serialize |
+| ---------- | ----- | ---- | ------------ |
+| serialize  | 4 239 | 235  | —            |
+| to_json    | 1 444 | 692  | 2.94x slower |
+| as_json    | 1 186 | 843  | 3.58x slower |
+| oj+as_json | 1 126 | 888  | 3.77x slower |
 
-Scaling is linear — the 3.6× advantage over `as_json` holds from 10 to 5000 records.
+Scaling is linear — the 3.6x 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`.
-3. Fallback — calls `as_json` on the association value.
+1. PostSerializer — has serialize, used directly.
+2. PostOpenapi — is a Controller, delegates to its resource.
+3. Fallback — calls as_json on the association value.
 
 ---
 
@@ -264,14 +366,14 @@ 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`
+- 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
 
 ---
 
@@ -281,8 +383,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 +392,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 +405,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 +416,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,13 +452,14 @@ attribute :nickname,     type: :string                    # request and response
 OpenapiBlocks watches for changes in:
 
 ```
+app/serializers/**/*.rb
 app/openapi/**/*.rb
 app/models/**/*.rb
 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.
 
 ---
 
@@ -369,4 +472,4 @@ The spec is automatically regenerated on the next request to `/docs/openapi.json
 
 ## License
 
-MIT (LICENSE.txt)
+MIT (LICENSE.txt)