openapi_blocks 0.3.1 → 0.4.1

data/README.pt-BR.md

@@ -1,38 +1,16 @@
 # OpenapiBlocks
 
-OpenapiBlocks é uma gem Rails que gera automaticamente documentação OpenAPI 3.0/3.1 a partir dos seus modelos ActiveRecord, validações do ActiveModel e rotas do Rails, inspirada em [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).
 
-Sem anotações manuais. Sem ruído de DSL nos controllers. Basta declarar o que deve ser exposto e o spec é gerado automaticamente.
+English version: [README.md](README.md)
 
-## Principais mudanças (recentes)
-- Versão padrão do OpenAPI: `3.1.0` (suportado: `3.1.0`, `3.0.3`).
-- A Swagger UI é servida no caminho onde a engine foi montada e usa endpoints do mesmo origin (same-origin) para evitar CORS — a UI mostra uma lista de servidores, mas buscará o spec a partir da URL montada.
-- A saída YAML é normalizada para chaves em string (`deep_stringify_keys`) para que o campo `openapi` seja reconhecido pelo Swagger UI.
-- O DSL `association` usa `read_only: true` para marcar associações como somente resposta e excluí-las dos schemas `*Input`; associações/atributos `read_only` continuam presentes nas respostas.
-- O `tags` é gerado no nível do documento a partir dos paths e pode ser customizado via `tags` nas classes e operações.
-- Referências de schema aceitam `Symbol` (ex.: `schema: :user`) e arrays com items como símbolos (ex.: `items: :user`).
-# OpenapiBlocks
-
-OpenapiBlocks é uma gem Rails que gera automaticamente documentação OpenAPI 3.0/3.1 a partir dos seus modelos ActiveRecord, validações do ActiveModel e rotas do Rails — inspirada em ActiveModel::Serializer.
-
-Sem anotações manuais. Sem ruído de DSL nos controllers. Basta declarar o que deve ser exposto e o spec é gerado automaticamente. Inclui um serializer interno de alto desempenho — aproximadamente 3.6× mais rápido que `as_json` com escalabilidade linear consistente.
-
-## Principais mudanças (recentes)
-- `OpenapiBlocks::Resource` e `OpenapiBlocks::Controller` foram introduzidos para separar responsabilidades de serialização e documentação.
-- Versão padrão do OpenAPI: `3.1.0` (suportado: `3.1.0`, `3.0.3`).
-- Scalar UI agora é servido em `/docs/scalar` ao lado da Swagger UI em `/docs`.
-- A Swagger UI usa endpoints same-origin para evitar problemas de CORS ao usar "Try it out"; a UI mostra servidores configurados, mas busca o spec a partir da URL montada da engine.
-- A saída YAML é normalizada para chaves em string (`deep_stringify_keys`) para que o campo `openapi` seja reconhecido pelo Swagger UI.
-- O DSL `association` utiliza `read_only: true` para marcar associações como somente-resposta e excluí-las dos schemas `*Input`; atributos/associações `read_only` continuam presentes em respostas.
-- `tags` são gerados no nível do documento a partir dos paths e podem ser customizados via `tags` nas classes e operações.
-- Referências de schema aceitam `Symbol` (ex.: `schema: :user`) e arrays com `items` como símbolos (ex.: `items: :user`).
-- O serializer compila um método extrator monolítico por classe em tempo de boot usando `class_eval`, eliminando ramificações por objeto e chamadas lambda em tempo de execução.
+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"
@@ -48,7 +26,7 @@ bundle install
 
 ## Configuração
 
-### 1. Monte a Engine
+### 1. Monte o Engine
 
 ```ruby
 # config/routes.rb
@@ -62,28 +40,30 @@ end
 Isso expõe:
 
 ```
-GET /docs               ->  Scalar UI
+GET /docs               ->  Scalar UI (padrão)
 GET /docs/swagger       ->  Swagger UI
-GET /docs/openapi.json  ->  OpenAPI spec in JSON
-GET /docs/openapi.yaml  ->  OpenAPI spec in YAML
+GET /docs/openapi.json  ->  Spec OpenAPI em JSON
+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.
+
 ```ruby
 # config/initializers/openapi_blocks.rb
 OpenapiBlocks.configure do |config|
-  config.openapi_version = "3.1.0"  # "3.0.3" ou "3.1.0"
+  config.openapi_version = "3.1.0"  # obrigatório — "3.0.3" ou "3.1.0"
 
   config.info do
-    title       "Minha API"
-    version     "1.0.0"
-    description "Documentação da API gerada automaticamente"
+    title       "Minha API"    # obrigatório
+    version     "1.0.0"        # obrigatório
+    description "Documentação gerada automaticamente"
 
     contact do
-      name  "Minha equipe"
-      email "api@mycompany.com"
-      url   "https://mycompany.com"
+      name  "Meu Time"
+      email "api@minhaempresa.com.br"
+      url   "https://minhaempresa.com.br"
     end
 
     license do
@@ -94,7 +74,7 @@ OpenapiBlocks.configure do |config|
 
   config.servers do
     server do
-      url         "https://api.mycompany.com"
+      url         "https://api.minhaempresa.com.br"
       description "Produção"
     end
 
@@ -104,7 +84,8 @@ OpenapiBlocks.configure do |config|
     end
   end
 
-  config.watch = :development  # auto-reload em mudanças de arquivo
+  config.watch          = :development  # recarrega automaticamente em desenvolvimento
+  config.auto_serialize = true          # opcional — veja Serialização Automática abaixo
 
   # opcional: esquemas de segurança
   config.security do
@@ -118,27 +99,28 @@ end
 
 ## Uso
 
-OpenapiBlocks fornece duas classes base com responsabilidades distintas:
+OpenapiBlocks oferece duas classes base com responsabilidades distintas:
 
-- `OpenapiBlocks::Resource` — define o model, campos, associações e lógica de serialização.
-- `OpenapiBlocks::Controller` — define operações da API, parâmetros e respostas para documentação.
-- `OpenapiBlocks::Base` — classe 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.
 
-### Resource + Controller (recomendado)
+### Recomendado: Serializer + Controller
 
 ```
 app/
+  serializers/
+    user_serializer.rb    ->  serialização + schema
+    post_serializer.rb
   openapi/
-    user_resource.rb    ->  serialização + schema
-    user_openapi.rb     ->  documentação da API
-    post_resource.rb
+    user_openapi.rb       ->  documentação da API
     post_openapi.rb
 ```
 
 ```ruby
-# app/openapi/user_resource.rb
-class UserResource < OpenapiBlocks::Resource
-  # o model User é inferido automaticamente pelo nome da classe
+# app/serializers/user_serializer.rb
+class UserSerializer < OpenapiBlocks::Serializer
+  # model User inferido automaticamente pelo nome da classe
 
   ignore :password_digest, :reset_password_token
 
@@ -148,39 +130,39 @@ class UserResource < OpenapiBlocks::Resource
   attribute :access_token, type: :string, read_only: true
   attribute :nickname,     type: :string
 
-  # método definido aqui — chamado na instância do recurso
+  # método definido aqui — chamado na instância do serializer
   def full_name
     "#{object.name} (#{object.email})"
   end
 
-  # ou omita o método e ele será delegado ao model automaticamente
+  # ou omita o método e ele delega para o model automaticamente
 end
 ```
 
 ```ruby
 # app/openapi/user_openapi.rb
 class UserOpenapi < OpenapiBlocks::Controller
-  resource UserResource
+  resource   UserSerializer
   controller UsersController
 
-  tags "Users"
+  tags "Usuários"
 
   operation :index do
-    summary     "List all users"
-    description "Returns a paginated list of active users"
+    summary     "Lista todos os usuários"
+    description "Retorna uma lista paginada de usuários ativos"
 
-    parameter :page,     in: :query, type: :integer, description: "Page number"
-    parameter :per_page, in: :query, type: :integer, description: "Items per page"
+    parameter :page,     in: :query, type: :integer, description: "Número da página"
+    parameter :per_page, in: :query, type: :integer, description: "Itens por página"
 
-    response 200, description: "List of users", schema: { type: :array, items: :User }
-    response 401, description: "Unauthorized"
+    response 200, description: "Lista de usuários", schema: { type: :array, items: :User }
+    response 401, description: "Não autorizado"
   end
 
   operation :show do
-    summary "Get a user"
+    summary "Busca um usuário"
 
-    response 200, description: "User found", schema: :User
-    response 404, description: "User not found"
+    response 200, description: "Usuário encontrado", schema: :User
+    response 404, description: "Não encontrado"
 
     no_security!
   end
@@ -190,20 +172,20 @@ 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 (legado, classe única)
+### Legado: Base (classe única)
 
 ```ruby
 # app/openapi/user_openapi.rb
 class UserOpenapi < OpenapiBlocks::Base
-  tags "Users"
+  tags "Usuários"
 
   ignore :password_digest
 
@@ -212,8 +194,8 @@ class UserOpenapi < OpenapiBlocks::Base
   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 }
+    summary  "Lista todos os usuários"
+    response 200, description: "Lista de usuários", schema: { type: :array, items: :User }
   end
 end
 ```
@@ -227,35 +209,67 @@ end
 
 ---
 
+## Serialização Automática
+
+Quando `config.auto_serialize = true`, o OpenapiBlocks intercepta todas as chamadas `render json:` e aplica automaticamente o serializer registrado — sem precisar chamar o serializer explicitamente nos controllers.
+
+```ruby
+# config/initializers/openapi_blocks.rb
+config.auto_serialize = true
+```
+
+```ruby
+# app/controllers/users_controller.rb
+def index
+  render json: User.all  # serializado automaticamente pelo UserSerializer
+end
+
+def show
+  render json: @user  # serializado automaticamente pelo UserSerializer
+end
+```
+
+O registro do serializer é automático por convenção (`UserSerializer` -> `User`). Para registro explícito:
+
+```ruby
+class AdminUserSerializer < OpenapiBlocks::Serializer
+  serializes User  # mapeia explicitamente este serializer para o model User
+end
+```
+
+Se nenhum serializer for encontrado, o OpenapiBlocks usa o comportamento padrão do Rails e registra um aviso no log.
+
+---
+
 ## Serializer
 
-O serializer interno compila um método extrator monolítico por classe em tempo de boot usando `class_eval`. Não há loops, nem indirection por lambda e nem ramificações em tempo de execução por objeto.
+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 |
-|---|---:|---:|---:|
-| 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 |
+| Método     | 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 |
 
-Escalamento é linear — a vantagem ~3.6× em relação a `as_json` se mantém de 10 a 5000 registros.
+A escalabilidade é linear — a vantagem de 3.6× sobre o `as_json` se mantém de 10 a 5000 registros.
 
-### Atributos virtuais e resolução de método
+### Atributos virtuais e resolução de métodos
 
-| Declarado com | Método no resource? | Chamada |
-|---|---:|---|
-| `attribute :full_name` | sim | `resource_instance.full_name` |
-| `attribute :full_name` | não | `object.full_name` (delegado ao model) |
-| coluna no db | — | `object.full_name` (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 de serializer de associação
+### Resolução do serializer de associações
 
-Para cada associação, a resolução procura na ordem:
+Para cada associação, o serializer resolve a classe na seguinte ordem:
 
-1. `PostResource` — se existir `serialize`, é usado diretamente.
-2. `PostOpenapi` — se for um `Controller`, delega ao seu `_resource`.
+1. `PostSerializer` — tem `serialize`, usado diretamente.
+2. `PostOpenapi` — é um `Controller`, delega para o `_resource`.
 3. Fallback — chama `as_json` no valor da associação.
 
 ---
@@ -273,16 +287,16 @@ class User < ApplicationRecord
 end
 ```
 
-OpenapiBlocks gera:
+O OpenapiBlocks gera:
 
-- `User` schema a partir de `db/schema.rb` (colunas e tipos)
-- `UserInput` schema para bodies de `POST`, `PUT` e `PATCH` (sem `id`, `created_at`, `updated_at` e campos `read_only`)
-- `required` a partir de validações `presence: true`
-- `minLength` e `maxLength` a partir de validações `length`
-- `minimum` e `maximum` a partir de validações `numericality`
-- `enum` a partir de validações `inclusion`
-- `format: "email"` a partir de validações de formato
-- Todos os paths a partir de `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`
 
 ---
 
@@ -292,20 +306,20 @@ Configure esquemas de segurança globais no 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
 ```
 
-Substitua a segurança por operação:
+Sobrescreva a segurança por operação:
 
 ```ruby
 operation :index do
-  security :bearerAuth   # apenas bearer nesta operação
+  security :bearerAuth  # só bearer nesta operação
 end
 
 operation :show do
-  no_security!           # endpoint público — sem autenticação
+  no_security!          # endpoint público — sem autenticação
 end
 ```
 
@@ -314,60 +328,61 @@ end
 ## Associações
 
 ```ruby
-association :company                                  # belongs_to — $ref para Company schema
-association :posts, type: :array                      # has_many — array de $ref para Post schema
-association :posts, type: :array, read_only: true     # excluído do UserInput (response only)
+association :company                               # belongs_to — $ref para schema Company
+association :posts, type: :array                   # has_many — array de $ref para schema Post
+association :posts, type: :array, read_only: true  # excluído do UserInput (somente resposta)
 ```
 
 ---
 
 ## Atributos Virtuais
 
-Atributos virtuais são campos que existem apenas na resposta da API e não no banco de dados.
+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   # 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  # somente resposta
+attribute :access_token, type: :string, read_only: true  # somente resposta
+attribute :nickname,     type: :string                   # requisição e resposta
 ```
 
 ---
 
-## Mapeamento de tipos
-
-| Tipo do 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 |
+## 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`               |
 
 ---
 
-## Auto-reload em desenvolvimento
+## Recarregamento Automático em Desenvolvimento
 
-OpenapiBlocks observa mudanças em:
+O OpenapiBlocks monitora mudanças em:
 
 ```
+app/serializers/**/*.rb
 app/openapi/**/*.rb
 app/models/**/*.rb
 config/routes.rb
 db/schema.rb
 ```
 
-O spec é regenerado automaticamente na próxima requisição para `/docs/openapi.json` sempre que qualquer um desses arquivos muda. Não é necessário 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.
 
 ---
 
@@ -380,4 +395,4 @@ O spec é regenerado automaticamente na próxima requisição para `/docs/openap
 
 ## Licença
 
-MIT (LICENSE.txt)
+[MIT](LICENSE.txt)

data/app/controllers/openapi_blocks/spec_controller.rb

@@ -3,7 +3,7 @@
 require "action_controller/api"
 
 module OpenapiBlocks
-  class SpecController < ActionController::API # rubocop:disable Style/Documentation
+  class SpecController < ActionController::API # rubocop:disable Style/Documentation,Metrics/ClassLength
     SWAGGER_UI_CSS             = "https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui.css"
     SWAGGER_UI_STANDALONE_JS   = "https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui-standalone-preset.js"
     SWAGGER_UI_JS              = "https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui-bundle.js"
@@ -30,7 +30,7 @@ module OpenapiBlocks
 
     private
 
-    def scalar_html
+    def scalar_html # rubocop:disable Metrics/MethodLength
       spec_url = "#{swagger_spec_base_url}.json"
       title    = "#{OpenapiBlocks.configuration.info.title} - Scalar"
 

data/lib/openapi_blocks/auto_serialize.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module OpenapiBlocks
+  module AutoSerialize # rubocop:disable Style/Documentation
+    def render(options = nil, extra = nil, &) # rubocop:disable Metrics/MethodLength
+      if auto_serialize_candidate?(options)
+        object     = options[:json]
+        serializer = Registry.resolve(object)
+
+        if serializer
+          log_serializer(object, serializer)
+          options = options.merge(json: serializer.serialize(object))
+        else
+          warn_no_serializer(object)
+        end
+      end
+
+      super
+    end
+
+    private
+
+    def auto_serialize_candidate?(options)
+      OpenapiBlocks.configuration.auto_serialize &&
+        options.is_a?(Hash) &&
+        options.key?(:json)
+    end
+
+    def log_serializer(object, serializer)
+      model = extract_model(object)
+      Rails.logger.debug(
+        "[OpenapiBlocks] #{model.name} serialized by #{serializer.name}"
+      )
+    end
+
+    def warn_no_serializer(object)
+      model = extract_model(object)
+      return unless model
+
+      Rails.logger.warn(
+        "[OpenapiBlocks] No serializer found for #{model.name}. " \
+        "Falling back to default Rails rendering. " \
+        "Create #{model.name}Serializer or use `serializes #{model.name}` explicitly."
+      )
+    end
+
+    def extract_model(object)
+      case object
+      when Array then object.first&.class
+      else object.respond_to?(:klass) ? object.klass : object.class
+      end
+    end
+  end
+end

data/lib/openapi_blocks/base.rb

@@ -1,48 +1,19 @@
 # frozen_string_literal: true
 
 module OpenapiBlocks
-  class Base # rubocop:disable Style/Documentation
-    include Serializer
+  # <b>DEPRECATED:</b> please use <tt>OpenapiBlocks::Controllers</tt> and <tt>OpenapiBlocks::Resources</tt> instead.
+  class Base
+    include Concerns::Schemable
+    include Concerns::Documentable
+    include Serialization
 
     class << self
-      attr_reader :_model, :_ignored, :_associations, :_virtual_attributes, :_operations, :_tags
-
-      def model(klass = nil)
-        klass ? @_model = klass : @_model ||= infer_model # rubocop:disable Naming/MemoizedInstanceVariableName
-      end
-
-      def ignore(*attributes)
-        @_ignored ||= []
-        @_ignored.concat(attributes.map(&:to_s))
-      end
-
-      def association(name, type: nil, read_only: false)
-        @_associations ||= []
-        @_associations << { name: name, type: type, read_only: read_only }
-      end
-
-      def attribute(name, **)
-        @_virtual_attributes ||= []
-        @_virtual_attributes << ({ name: name, ** })
-      end
-
-      def operation(action, &block)
-        @_operations ||= {}
-        builder = OperationBuilder.new
-        builder.instance_eval(&block) if block
-        @_operations[action] = builder
-      end
-
-      def tags(*values)
-        values.any? ? @_tags = values : @_tags
-      end
-
       private
 
       def infer_model
         model_name = name
                      .gsub(/Openapi$/, "")
-                     .gsub(/Resource$/, "")
+                     .gsub(/Serializer$/, "")
                      .split("::")
                      .last
 

data/lib/openapi_blocks/builder.rb

@@ -4,21 +4,53 @@ require_relative "spec/document"
 
 module OpenapiBlocks
   class Builder # rubocop:disable Style/Documentation
+    REQUIRED_CONFIG_ERROR = <<~MSG
+      OpenapiBlocks is not configured. Add an initializer:
+
+        # config/initializers/openapi_blocks.rb
+        OpenapiBlocks.configure do |config|
+          config.openapi_version = "3.1.0"  # required: "3.0.3" or "3.1.0"
+
+          config.info do
+            title   "My API"   # required
+            version "1.0.0"    # required
+          end
+        end
+    MSG
+
     def self.build
       new.build
     end
 
     def build
+      validate_configuration!
       Spec::Document.new(openapi_classes).build
     end
 
     private
 
+    def validate_configuration! # rubocop:disable Metrics/CyclomaticComplexity
+      config = OpenapiBlocks.configuration
+      errors = []
+
+      unless config.configured?
+        errors << "config.openapi_version or config.info must be defined — call OpenapiBlocks.configure"
+      end
+      errors << "config.info.title is required"   if config.info&.title.blank?
+      errors << "config.info.version is required" if config.info&.version.blank?
+
+      return if errors.empty?
+
+      raise Error, "#{REQUIRED_CONFIG_ERROR}\nMissing:\n#{errors.map { |e| "  - #{e}" }.join("\n")}"
+    end
+
     def openapi_classes
       ObjectSpace.each_object(Class).select do |klass|
         name = Module.instance_method(:name).bind_call(klass)
-        name&.end_with?("Openapi") &&
-          (klass < OpenapiBlocks::Base || klass < OpenapiBlocks::Controller)
+        next unless name&.end_with?("Openapi")
+
+        klass < OpenapiBlocks::Base ||
+          klass < OpenapiBlocks::Controller
       end
     end
   end