openapi_blocks 0.4.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eafa1f0685d4c659609b5116dfac6e7204cee4bd5c60ea882417aebbe4cd67dd
-  data.tar.gz: db613ff23df3f705b70f126f02a0d03334fffe8a8fcbfd3dbe563343fce69ef8
+  metadata.gz: 61f36b05bd60171d8f0a821a4775d65af84b9180e4221b095a8eb49632af0a41
+  data.tar.gz: 604229f12f550977abad1b52859582490b4bb66cb1bce7694bb24a9b7c942324
 SHA512:
-  metadata.gz: f88f54dcc99be63820da03cedaa9062d5e1c3e185c1cbf0d6aa3ac2c00f066b9ea75002dd1e8d4061f51c0f4bb71d606dc5b632de4f80870f3c598bd47312ef7
-  data.tar.gz: 75027794cbdebde235211302cc5da8495f2dba128441cdd8d94bfea4d7808acd1a66ef40569f768698c5c2b32fba205f99c71305673105b0229276d4c9c9e505
+  metadata.gz: 470ab2f51a7f5a6434c2e3361e0f040cd81e9cd811324f114e14a56909d821b0a5e4fdb4a858b657929303c7f4f99b7ace5a424a76ff2d9b6bb994ea9c308c00
+  data.tar.gz: '0900adcc92411360fe6eebb836cf8c424ee45bd435a169f135a572f5d0efe3d55bfede29e6e618f5ae8ad3e48f060e4204161f8afdd3597f822e15b9bb59e1af'

data/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-06-03
+
+- `OpenapiBlocks::Serializer` optmize serialization using frozen string constants as hash keys to reduce object allocations
+
+## [0.5.0] - 2026-06-02
+
+- Added generators
+
 ## [0.4.1] - 2026-06-02
 
 - Change parallel version
@@ -146,5 +154,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `SpecController#ui` action serving Swagger UI with JSON/YAML spec switcher
 
 [Unreleased]: https://github.com/evotechbuilder/openapi_blocks/compare/v0.2.0...HEAD
+[0.6.0]: https://github.com/evotechbuilder/openapi_blocks/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/evotechbuilder/openapi_blocks/compare/v0.4.1...v0.5.0
+[0.4.1]: https://github.com/evotechbuilder/openapi_blocks/compare/v0.4.0...v0.4.1
+[0.4.0]: https://github.com/evotechbuilder/openapi_blocks/compare/v0.3.1...v0.4.0
+[0.3.1]: https://github.com/evotechbuilder/openapi_blocks/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/evotechbuilder/openapi_blocks/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/evotechbuilder/openapi_blocks/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/evotechbuilder/openapi_blocks/releases/tag/v0.1.0

data/README.md

@@ -1,16 +1,16 @@
 # 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](README.pt-BR.md)
+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.
+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.
 
 ---
 
 ## Installation
 
-Add to your `Gemfile`:
+Add to your Gemfile:
 
 ```ruby
 gem "openapi_blocks"
@@ -24,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
@@ -48,7 +112,7 @@ 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.
+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
@@ -101,9 +165,9 @@ end
 
 OpenapiBlocks provides two base classes with distinct responsibilities:
 
-- `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.
+- 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.
 
 ### Recommended: Serializer + Controller
 
@@ -142,7 +206,7 @@ end
 ```ruby
 # app/openapi/user_openapi.rb
 class UserOpenapi < OpenapiBlocks::Controller
-  resource   UserSerializer
+  resource   UserSerializer  # links to the serializer — schema is derived from it
   controller UsersController
 
   tags "Users"
@@ -169,6 +233,19 @@ 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
@@ -229,7 +306,7 @@ def show
 end
 ```
 
-Serializer registration is automatic by convention (`UserSerializer` -> `User`). For explicit registration:
+Serializer registration is automatic by convention (UserSerializer -> User). For explicit registration:
 
 ```ruby
 class AdminUserSerializer < OpenapiBlocks::Serializer
@@ -243,34 +320,41 @@ If no serializer is found, OpenapiBlocks falls back to default Rails rendering a
 
 ## 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)
 
 | 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 |
+|------------|-------|------|--------------|
+| serialize  | 4 504 | 198  | —            |
+| to_json    | 1 444 | 692  | 2.89x slower |
+| as_json    | 1 179 | 453  | 2.81x slower |
+| oj+as_json | 1 126 | 572  | 2.89x slower |
+| AMS        |   559 | 178  | 9.02x slower |
+
+Scaling is linear — the 2.81x advantage over as_json holds from 10 to 5000 records.
+
+### Memory Allocation
 
-Scaling is linear — the 3.6× advantage over `as_json` holds from 10 to 5000 records.
+OpenapiBlocks:  20MB / 225k objects  — fastest and lowest memory
+as_json:       116MB / 1.2M objects  — 2.81x slower, 5.6x more memory
+AMS:           260MB / 2.7M objects  — 9x slower,   13x more memory
 
 ### Virtual attributes and method resolution
 
-| 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)             |
+| 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. `PostSerializer` — 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.
 
 ---
 
@@ -289,14 +373,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
 
 ---
 
@@ -339,10 +423,10 @@ association :posts, type: :array, read_only: true  # excluded from UserInput (re
 
 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
@@ -354,19 +438,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             |
 
 ---
 
@@ -382,7 +466,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.
 
 ---
 
@@ -395,4 +479,4 @@ The spec is automatically regenerated on the next request to `/docs/openapi.json
 
 ## License
 
-[MIT](LICENSE.txt)
+MIT (LICENSE.txt)

data/README.pt-BR.md

@@ -1,16 +1,16 @@
 # OpenapiBlocks
 
-OpenapiBlocks é uma gem Rails que gera automaticamente documentação OpenAPI 3.0/3.1 a partir dos seus models ActiveRecord, validações ActiveModel e rotas do Rails — inspirada no [ActiveModel::Serializer](https://github.com/rails-api/active_model_serializers).
+OpenapiBlocks é uma gem Rails que gera automaticamente documentação OpenAPI 3.0/3.1 a partir dos seus models ActiveRecord, validações ActiveModel e rotas do Rails — inspirada no ActiveModel::Serializer (https://github.com/rails-api/active_model_serializers).
 
-English version: [README.md](README.md)
+English version: README.md
 
-Sem anotações manuais. Sem DSL nos controllers. Basta declarar o que expor e a spec é gerada automaticamente. Inclui um serializer de alta performance — ~3.6× mais rápido que `as_json` com escalabilidade linear de 10 a 5000 registros.
+Sem anotações manuais. Sem DSL nos controllers. Basta declarar o que expor e a spec é gerada automaticamente. Inclui um serializer de alta performance — ~3.6× mais rápido que as_json com escalabilidade linear de 10 a 5000 registros.
 
 ---
 
 ## Instalação
 
-Adicione ao seu `Gemfile`:
+Adicione ao seu Gemfile:
 
 ```ruby
 gem "openapi_blocks"
@@ -24,6 +24,70 @@ bundle install
 
 ---
 
+## Generators
+
+O OpenapiBlocks oferece três generators para começar rapidamente.
+
+### Install
+
+```bash
+rails generate openapi_blocks:install
+```
+
+Cria `config/initializers/openapi_blocks.rb` com todas as opções disponíveis comentadas, e monta o engine no `config/routes.rb`:
+
+```ruby
+mount OpenapiBlocks::Engine => "/docs"
+```
+
+### Openapi
+
+```bash
+rails generate openapi_blocks:openapi User
+```
+
+Cria `app/openapi/user_openapi.rb` com todas as opções de DSL disponíveis comentadas:
+
+```ruby
+# app/openapi/user_openapi.rb
+class UserOpenapi < OpenapiBlocks::Controller
+  # resource UserSerializer
+  # controller UsersController
+
+  # tags "Usuários"
+
+  # operation :index do
+  #   summary     "Lista todos os usuários"
+  #   response 200, description: "Lista de usuários", schema: { type: :array, items: :User }
+  # end
+end
+```
+
+### Serializer
+
+```bash
+rails generate openapi_blocks:serializer User
+```
+
+Cria `app/serializers/user_serializer.rb` com todas as opções de DSL disponíveis comentadas:
+
+```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
+```
+
+---
+
 ## Configuração
 
 ### 1. Monte o Engine
@@ -48,7 +112,7 @@ GET /docs/openapi.yaml  ->  Spec OpenAPI em YAML
 
 ### 2. Configure o initializer
 
-`OpenapiBlocks.configure` é obrigatório. A gem lança `OpenapiBlocks::Error` na primeira requisição se nunca foi chamado ou se `info.title` / `info.version` estiverem em branco.
+OpenapiBlocks.configure é obrigatório. A gem lança OpenapiBlocks::Error na primeira requisição se nunca foi chamado ou se info.title / info.version estiverem em branco.
 
 ```ruby
 # config/initializers/openapi_blocks.rb
@@ -99,11 +163,11 @@ end
 
 ## Uso
 
-OpenapiBlocks oferece duas classes base com responsabilidades distintas:
+O OpenapiBlocks oferece duas classes base com responsabilidades distintas:
 
-- `OpenapiBlocks::Serializer` — define o model, campos, associações e lógica de serialização. Fica em `app/serializers/`.
-- `OpenapiBlocks::Controller` — define operações, parâmetros e respostas para documentação. Fica em `app/openapi/`.
-- `OpenapiBlocks::Base` — classe base legada que combina ambas as responsabilidades. Ainda suportada.
+- OpenapiBlocks::Serializer — define o model, campos, associações e lógica de serialização. Fica em app/serializers/.
+- OpenapiBlocks::Controller — define operações, parâmetros e respostas para documentação. Fica em app/openapi/.
+- OpenapiBlocks::Base — classe base legada que combina ambas as responsabilidades. Ainda suportada.
 
 ### Recomendado: Serializer + Controller
 
@@ -142,7 +206,7 @@ end
 ```ruby
 # app/openapi/user_openapi.rb
 class UserOpenapi < OpenapiBlocks::Controller
-  resource   UserSerializer
+  resource   UserSerializer  # vincula ao serializer — o schema é derivado dele
   controller UsersController
 
   tags "Usuários"
@@ -169,6 +233,19 @@ class UserOpenapi < OpenapiBlocks::Controller
 end
 ```
 
+#### Como o schema OpenAPI é gerado
+
+Quando `resource UserSerializer` é declarado em um `Controller`, o OpenapiBlocks deriva o schema OpenAPI diretamente do serializer — não do model. Isso garante que o que está documentado é exatamente o que a API retorna.
+
+O schema é construído a partir de três fontes no serializer:
+
+- Colunas do ActiveRecord — lidas do `db/schema.rb` via o model inferido. Os tipos das colunas são mapeados para tipos OpenAPI automaticamente.
+- Declarações `attribute` — campos virtuais que não existem no banco. Campos declarados com `read_only: true` aparecem no schema de resposta `User` mas são excluídos do schema de requisição `UserInput`.
+- Declarações `association` — resolvidas como `$ref` para o schema associado. Associações com `read_only: true` aparecem na resposta mas são excluídas do `UserInput`.
+- Declarações `ignore` — colunas excluídas de ambos os schemas.
+
+O schema `UserInput` (usado nos request bodies de POST, PUT e PATCH) é derivado automaticamente do schema `User` removendo `id`, `created_at`, `updated_at` e qualquer campo marcado com `read_only: true`.
+
 ```ruby
 # app/controllers/users_controller.rb
 def index
@@ -229,7 +306,7 @@ def show
 end
 ```
 
-O registro do serializer é automático por convenção (`UserSerializer` -> `User`). Para registro explícito:
+O registro do serializer é automático por convenção (UserSerializer -> User). Para registro explícito:
 
 ```ruby
 class AdminUserSerializer < OpenapiBlocks::Serializer
@@ -243,34 +320,41 @@ Se nenhum serializer for encontrado, o OpenapiBlocks usa o comportamento padrão
 
 ## Serializer
 
-O serializer compila um método extrator monolítico por classe no boot usando `class_eval`. Sem loops, sem indireção via lambda e sem branching por objeto em tempo de execução.
+O serializer compila um método extrator monolítico por classe no boot usando class_eval. Sem loops, sem indireção via lambda e sem branching por objeto em tempo de execução.
 
 ### Performance (200 registros, arm64, Ruby 4.0)
 
-| Método     | i/s   | μs/i | vs serialize |
+| Method     | i/s   | μs/i | vs serialize |
 |------------|-------|------|--------------|
-| serialize  | 4 239 | 235  | —            |
-| to_json    | 1 444 | 692  | 2.94× mais lento |
-| as_json    | 1 186 | 843  | 3.58× mais lento |
-| oj+as_json | 1 126 | 888  | 3.77× mais lento |
+| serialize  | 4 504 | 198  | —            |
+| to_json    | 1 444 | 692  | 2.89x mais lento |
+| as_json    | 1 179 | 453  | 2.81x mais lento |
+| oj+as_json | 1 126 | 572  | 2.89x mais lento |
+| AMS        |   559 | 178  | 9.02x mais lento |
+
+A escalabilidade é linear — a vantagem de 2.81× sobre o as_json se mantém de 10 a 5000 registros.
+
+### Memória alocada
 
-A escalabilidade é linear — a vantagem de 3.6× sobre o `as_json` se mantém de 10 a 5000 registros.
+OpenapiBlocks: 20MB / 225k objetos — mais rápido e com menor consumo de memória
+as_json:       116MB / 1,2M objetos — 2,81x mais lento, 5,6x mais memória
+AMS:           260MB / 2,7M objetos — 9x mais lento, 13x mais memória
 
 ### Atributos virtuais e resolução de métodos
 
-| Declarado com          | Método no serializer? | Chama                                   |
-|------------------------|-----------------------|-----------------------------------------|
-| `attribute :full_name` | sim                   | `serializer_instance.full_name`         |
-| `attribute :full_name` | não                   | `object.full_name` (delegado ao model)  |
-| coluna no banco        | —                     | `object.attribute` (direto)             |
+| Declarado com        | Método no serializer? | Chama                                |
+| -------------------- | --------------------- | ------------------------------------ |
+| attribute :full_name | sim                   | serializer_instance.full_name        |
+| attribute :full_name | não                   | object.full_name (delegado ao model) |
+| coluna no banco      | —                     | object.attribute (direto)            |
 
 ### Resolução do serializer de associações
 
 Para cada associação, o serializer resolve a classe na seguinte ordem:
 
-1. `PostSerializer` — tem `serialize`, usado diretamente.
-2. `PostOpenapi` — é um `Controller`, delega para o `_resource`.
-3. Fallback — chama `as_json` no valor da associação.
+1. PostSerializer — tem serialize, usado diretamente.
+2. PostOpenapi — é um Controller, delega para o \_resource.
+3. Fallback — chama as_json no valor da associação.
 
 ---
 
@@ -289,14 +373,14 @@ end
 
 O OpenapiBlocks gera:
 
-- Schema `User` a partir das colunas e tipos do `db/schema.rb`
-- Schema `UserInput` para os request bodies de `POST`, `PUT` e `PATCH` (sem `id`, `created_at`, `updated_at` e campos `read_only`)
-- Campos `required` a partir das validações `presence: true`
-- `minLength`, `maxLength` a partir das validações `length`
-- `minimum`, `maximum` a partir das validações `numericality`
-- `enum` a partir das validações `inclusion`
-- `format: "email"` a partir das validações de formato
-- Todos os paths a partir do `config/routes.rb`
+- Schema User a partir das colunas e tipos do db/schema.rb
+- Schema UserInput para os request bodies de POST, PUT e PATCH (sem id, created_at, updated_at e campos read_only)
+- Campos required a partir das validações presence: true
+- minLength, maxLength a partir das validações length
+- minimum, maximum a partir das validações numericality
+- enum a partir das validações inclusion
+- format: "email" a partir das validações de formato
+- Todos os paths a partir do config/routes.rb
 
 ---
 
@@ -339,10 +423,10 @@ association :posts, type: :array, read_only: true  # excluído do UserInput (som
 
 Atributos virtuais são campos que existem na resposta da API mas não no banco de dados.
 
-| Opção              | Descrição                              | Aparece em User | Aparece em UserInput |
-|--------------------|----------------------------------------|:---------------:|:--------------------:|
-| `read_only: true`  | Campos calculados ou gerados pelo sistema |    SIM       |        NÃO           |
-| `read_only: false` | Campos que o cliente pode enviar e receber | SIM         |        SIM           |
+| Opção            | Descrição                                  | Aparece em User | Aparece em UserInput |
+| ---------------- | ------------------------------------------ | :-------------: | :------------------: |
+| read_only: true  | Campos calculados ou gerados pelo sistema  |       SIM       |         NÃO          |
+| read_only: false | Campos que o cliente pode enviar e receber |       SIM       |         SIM          |
 
 ```ruby
 attribute :full_name,    type: :string, read_only: true  # somente resposta
@@ -354,19 +438,19 @@ attribute :nickname,     type: :string                   # requisição e respos
 
 ## Mapeamento de Tipos
 
-| Tipo ActiveRecord | Tipo OpenAPI           |
-|-------------------|------------------------|
-| `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`               |
+| Tipo ActiveRecord | Tipo OpenAPI       |
+| ----------------- | ------------------ |
+| 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             |
 
 ---
 
@@ -382,7 +466,7 @@ config/routes.rb
 db/schema.rb
 ```
 
-A spec é regenerada automaticamente na próxima requisição a `/docs/openapi.json` sempre que algum desses arquivos for alterado. Sem precisar reiniciar o servidor.
+A spec é regenerada automaticamente na próxima requisição a /docs/openapi.json sempre que algum desses arquivos for alterado. Sem precisar reiniciar o servidor.
 
 ---
 
@@ -395,4 +479,4 @@ A spec é regenerada automaticamente na próxima requisição a `/docs/openapi.j
 
 ## Licença
 
-[MIT](LICENSE.txt)
+MIT (LICENSE.txt)

data/lib/generators/openapi_blocks/install/install_generator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module OpenapiBlocks
+  module Generators
+    class InstallGenerator < Rails::Generators::Base # rubocop:disable Style/Documentation
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates an OpenapiBlocks initializer and mounts the engine in routes.rb"
+
+      def create_initializer
+        template "initializer.rb.tt", "config/initializers/openapi_blocks.rb"
+      end
+
+      def mount_engine
+        route 'mount OpenapiBlocks::Engine => "/docs"'
+      end
+    end
+  end
+end

data/lib/generators/openapi_blocks/install/templates/initializer.rb.tt

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+OpenapiBlocks.configure do |config|
+  # config.openapi_version = "3.1.0"  # required — "3.0.3" or "3.1.0"
+
+  # config.auto_serialize = true  # default is false
+
+  config.info do
+    title       "My API"  # required
+    version     "1.0.0"   # required
+    description "API documentation generated automatically"
+
+    # contact do
+    #   name  "My Team"
+    #   email "api@mycompany.com"
+    #   url   "https://mycompany.com"
+    # end
+
+    # license do
+    #   name "MIT"
+    #   url  "https://opensource.org/licenses/MIT"
+    # end
+  end
+
+  # config.servers do
+  #   server do
+  #     url         "http://localhost:3000"
+  #     description "Development"
+  #   end
+  # end
+
+  # config.security do
+  #   bearer_token format: "JWT"                   # Authorization: Bearer <token>
+  #   api_key      name: "X-API-Key", in: :header  # X-API-Key: <key>
+  # end
+end

data/lib/generators/openapi_blocks/openapi/openapi_generator.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module OpenapiBlocks
+  module Generators
+    class OpenapiGenerator < Rails::Generators::NamedBase # rubocop:disable Style/Documentation
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates an OpenapiBlocks Controller class in app/openapi/"
+
+      def create_openapi_file
+        template "openapi.rb.tt", "app/openapi/#{file_name}_openapi.rb"
+      end
+    end
+  end
+end

data/lib/generators/openapi_blocks/openapi/templates/openapi.rb.tt

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+class <%= class_name %>Openapi < OpenapiBlocks::Controller
+  # resource <%= class_name %>Serializer
+  # controller <%= class_name %>Controller
+
+  # tags "<%= class_name.pluralize %>"
+
+  # operation :index do
+  #   summary     "List all <%= class_name.pluralize.downcase %>"
+  #   description "Returns a paginated list of <%= class_name.pluralize.downcase %>"
+  #
+  #   parameter :page,     in: :query, type: :integer, description: "Page number"
+  #   parameter :per_page, in: :query, type: :integer, description: "Items per page"
+  #
+  #   response 200, description: "List of <%= class_name.pluralize.downcase %>", schema: { type: :array, items: :<%= class_name %> }
+  #   response 401, description: "Unauthorized"
+  # end
+
+  # operation :show do
+  #   summary "Get a <%= class_name.downcase %>"
+  #
+  #   response 200, description: "<%= class_name %> found",     schema: :<%= class_name %>
+  #   response 404, description: "<%= class_name %> not found"
+  # end
+
+  # operation :create do
+  #   summary "Create a <%= class_name.downcase %>"
+  #
+  #   response 201, description: "<%= class_name %> created", schema: :<%= class_name %>
+  #   response 422, description: "Invalid data"
+  # end
+
+  # operation :update do
+  #   summary "Update a <%= class_name.downcase %>"
+  #
+  #   response 200, description: "<%= class_name %> updated",     schema: :<%= class_name %>
+  #   response 404, description: "<%= class_name %> not found"
+  #   response 422, description: "Invalid data"
+  # end
+
+  # operation :destroy do
+  #   summary "Delete a <%= class_name.downcase %>"
+  #
+  #   response 200, description: "<%= class_name %> deleted"
+  #   response 404, description: "<%= class_name %> not found"
+  # end
+end

data/lib/generators/openapi_blocks/serializer/serializer_generator.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module OpenapiBlocks
+  module Generators
+    class SerializerGenerator < Rails::Generators::NamedBase # rubocop:disable Style/Documentation
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates an OpenapiBlocks Serializer class in app/serializers/"
+
+      def create_serializer_file
+        template "serializer.rb.tt", "app/serializers/#{file_name}_serializer.rb"
+      end
+    end
+  end
+end

data/lib/generators/openapi_blocks/serializer/templates/serializer.rb.tt

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class <%= class_name %>Serializer < OpenapiBlocks::Serializer
+  # model <%= class_name %> is inferred automatically from the class name
+
+  # 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

data/lib/openapi_blocks/railtie.rb

@@ -4,6 +4,12 @@ require "rails"
 
 module OpenapiBlocks
   class Railtie < Rails::Railtie # rubocop:disable Style/Documentation
+    generators do
+      require "generators/openapi_blocks/install/install_generator"
+      require "generators/openapi_blocks/openapi/openapi_generator"
+      require "generators/openapi_blocks/serializer/serializer_generator"
+    end
+
     initializer "openapi_blocks.autoload", before: :set_autoload_paths do |app|
       app.config.eager_load_paths << app.root.join("app/openapi")
       app.config.eager_load_paths << app.root.join("app/serializers")

data/lib/openapi_blocks/serialization.rb

@@ -30,17 +30,28 @@ module OpenapiBlocks
 
       private
 
-      def build_compiled_extractor # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+      def build_compiled_extractor # rubocop:disable Metrics/AbcSize,Metrics/MethodLength,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
         classified = classify_fields
+        classified[:association].each { |field| build_assoc_method(field) }
 
-        model_lines = classified[:model].map { |f| %("#{f}" => object.public_send("#{f}")) }
-        virtual_lines   = classified[:virtual].map   { |f| %("#{f}" => inst.public_send("#{f}")) }
-        delegated_lines = classified[:delegated].map { |f| %("#{f}" => object.public_send("#{f}")) }
-        assoc_lines     = classified[:association].map do |f|
-          %("#{f}" => _serialize_assoc_#{f}(object))
+        all_fields = classified.values.flatten
+        all_fields.each do |f|
+          const_name = "KEY_#{f.upcase}"
+          const_set(const_name, f.freeze) unless const_defined?(const_name)
         end
 
-        classified[:association].each { |field| build_assoc_method(field) }
+        model_lines = classified[:model].map do |f|
+          %(#{name}::KEY_#{f.upcase} => object.#{f})
+        end
+        delegated_lines = classified[:delegated].map do |f|
+          %(#{name}::KEY_#{f.upcase} => object.#{f})
+        end
+        virtual_lines = classified[:virtual].map do |f|
+          %(#{name}::KEY_#{f.upcase} => inst.#{f})
+        end
+        assoc_lines = classified[:association].map do |f|
+          %(#{name}::KEY_#{f.upcase} => _serialize_assoc_#{f}(object))
+        end
 
         all_lines = (model_lines + delegated_lines + virtual_lines + assoc_lines).join(",\n        ")
 
@@ -86,7 +97,7 @@ module OpenapiBlocks
             def self._serialize_assoc_#{field}(object)
               val = object.public_send(:#{assoc_name})
               return nil if val.nil?
-              val.map { |v| #{serializer}.serialize(v) }
+              #{serializer}.serialize(val)
             end
           RUBY
         else

data/lib/openapi_blocks/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpenapiBlocks
-  VERSION = "0.4.1"
+  VERSION = "0.6.0"
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: openapi_blocks
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Caio Santos
+autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-06-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: oj
@@ -139,6 +140,12 @@ files:
 - Rakefile
 - app/controllers/openapi_blocks/spec_controller.rb
 - config/routes.rb
+- lib/generators/openapi_blocks/install/install_generator.rb
+- lib/generators/openapi_blocks/install/templates/initializer.rb.tt
+- lib/generators/openapi_blocks/openapi/openapi_generator.rb
+- lib/generators/openapi_blocks/openapi/templates/openapi.rb.tt
+- lib/generators/openapi_blocks/serializer/serializer_generator.rb
+- lib/generators/openapi_blocks/serializer/templates/serializer.rb.tt
 - lib/openapi_blocks.rb
 - lib/openapi_blocks/auto_serialize.rb
 - lib/openapi_blocks/base.rb
@@ -180,6 +187,7 @@ metadata:
   source_code_uri: https://github.com/evotechbuilder/openapi_blocks
   changelog_uri: https://github.com/evotechbuilder/openapi_blocks/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -194,7 +202,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 3.4.1
+signing_key:
 specification_version: 4
 summary: OpenAPI 3.0/3.1 documentation and high-performance serializer for Rails
 test_files: []