openapi_blocks 0.3.1 → 0.5.0

data/README.pt-BR.md

@@ -1,32 +1,10 @@
 # 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
 
-## 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.
 
 ---
 
@@ -46,9 +24,73 @@ 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 a Engine
+### 1. Monte o Engine
 
 ```ruby
 # config/routes.rb
@@ -62,28 +104,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 +138,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 +148,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 +163,28 @@ end
 
 ## Uso
 
-OpenapiBlocks fornece duas classes base com responsabilidades distintas:
+O 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,62 +194,75 @@ 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  # vincula ao serializer — o schema é derivado dele
   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
 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
-  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 +271,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,36 +286,68 @@ 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   | us/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`.
-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.
 
 ---
 
@@ -273,16 +364,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 +383,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 +405,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.
 
 ---
 

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/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