openapi_blocks 0.2.0

data/README.pt-BR.md

@@ -0,0 +1,495 @@
+# 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).
+
+Sem anotações manuais. Sem ruído de DSL nos controllers. Basta declarar o que deve ser exposto e o spec é gerado automaticamente.
+
+---
+
+## Instalação
+
+Adicione ao seu `Gemfile`:
+
+```ruby
+gem "openapi_blocks"
+```
+
+Depois execute:
+
+```bash
+bundle install
+```
+
+---
+
+## Configuração
+
+### 1. Monte a Engine
+
+```ruby
+# config/routes.rb
+```
+
+```ruby
+Rails.application.routes.draw do
+  mount OpenapiBlocks::Engine => "/docs"
+  resources :users
+end
+```
+
+Isso expõe:
+
+<br />
+GET /docs/openapi.json
+
+<br />
+GET /docs/openapi.yaml
+
+### 2. Configure o initializer
+
+```ruby
+# config/initializers/openapi_blocks.rb
+
+OpenapiBlocks.configure do |config|
+  # Versões suportadas: "3.1.0" e "3.0.3". O padrão desta gem é "3.1.0".
+  config.openapi_version = "3.1.0" # "3.0.3" ou "3.1.0"
+  config.info do
+    title       "Minha API"
+    version     "1.0.0"
+    description "Documentação da API gerada automaticamente"
+    contact do
+      name  "Minha equipe"
+      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         "https://api.mycompany.com"
+      description "Produção"
+    end
+    server do
+      url         "http://localhost:3000"
+      description "Desenvolvimento"
+    end
+  end
+  config.watch = :development # recarrega automaticamente em mudanças de arquivo
+end
+```
+
+Observações:
+
+- A interface Swagger UI fornecida pela engine prioriza a origem atual da
+  requisição (same-origin) como servidor primário para evitar problemas de
+  CORS ao usar o recurso "Try it out". Você ainda pode listar outros
+  servidores em `config.servers` apenas para fins informacionais; a UI
+  buscará o documento OpenAPI a partir da URL do spec na mesma origem,
+  construída automaticamente com o prefixo usado ao montar a engine.
+
+---
+
+## Uso
+
+### Criando uma classe OpenAPI
+
+Crie um arquivo em `app/openapi/` seguindo a mesma convenção de nomes do ActiveModel::Serializer:
+
+```text
+app/
+    openapi/
+        user_openapi.rb     →  User model
+        post_openapi.rb     →  Post model
+        order_openapi.rb    →  Order model
+```
+
+```ruby
+# app/openapi/user_openapi.rb
+
+class UserOpenapi < OpenapiBlocks::Base
+  # o model User é inferido automaticamente pelo nome da classe
+
+  # ignora campos sensíveis ou desnecessários
+  ignore :password_digest, :reset_password_token
+
+  # associações opt-in
+  association :company
+  association :posts, type: :array
+
+  # atributos virtuais (não existem no banco)
+  attribute :full_name, type: :string
+  attribute :token, type: :string, read_only: true
+end
+```
+
+### O que é gerado automaticamente
+
+Dado este model:
+
+```ruby
+class User < ApplicationRecord
+  validates :name, presence: true, length: { minimum: 2, maximum: 100 }
+  validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
+  validates :age, numericality: { greater_than: 0 }
+  validates :role, inclusion: { in: %w[admin user guest] }
+end
+```
+
+OpenapiBlocks gera:
+
+- `User` schema a partir das colunas e tipos de `db/schema.rb`
+- `UserInput` schema para bodies de request de `POST`, `PUT` e `PATCH` (sem `id`, `created_at`, `updated_at`)
+- `UserInput` schema para bodies de request de `POST`, `PUT` e `PATCH` (sem `id`, `created_at`, `updated_at` e atributos virtuais marcados como `read_only`)
+- campos `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`
+
+### Atributos Virtuais
+
+Atributos virtuais são campos que existem apenas na resposta da API e 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          |
+
+```ruby
+attribute :full_name,    type: :string, read_only: true   # apenas resposta
+attribute :access_token, type: :string, read_only: true   # apenas resposta
+attribute :nickname,     type: :string                    # request e response
+```
+
+### Customizando operações
+
+````ruby
+# app/openapi/user_openapi.rb
+class UserOpenapi < OpenapiBlocks::Base
+  operation :index do
+    summary     "Listar todos os usuários"
+    description "Retorna uma lista paginada de usuários ativos"
+    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: "Lista de usuários", schema: { type: :array, items: :User }
+    response 401, description: "Não autorizado"
+  end
+
+  operation :show do
+    summary "Buscar um usuário"
+    response 200, description: "Usuário encontrado", schema: :User
+    response 404, description: "Usuário não encontrado"
+  end
+
+  operation :create do
+    # 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.
+
+    ---
+
+    ## Instalação
+
+    Adicione ao seu `Gemfile`:
+
+    ```ruby
+    gem "openapi_blocks"
+    ```
+
+    Depois execute:
+
+    ```bash
+    bundle install
+    ```
+
+    ---
+
+    ## Configuração
+
+    ### 1. Monte a Engine
+
+    ```ruby
+    # config/routes.rb
+    Rails.application.routes.draw do
+      mount OpenapiBlocks::Engine => "/docs"
+
+      resources :users
+    end
+    ```
+
+    Isso expõe:
+
+    ```
+    GET /docs               ->  Swagger UI
+    GET /docs/openapi.json  ->  OpenAPI spec em JSON
+    GET /docs/openapi.yaml  ->  OpenAPI spec em YAML
+    ```
+
+    ### 2. Configure o initializer
+
+    ```ruby
+    # config/initializers/openapi_blocks.rb
+    OpenapiBlocks.configure do |config|
+      # Versões suportadas: "3.1.0" e "3.0.3". O padrão desta gem é "3.1.0".
+      config.openapi_version = "3.1.0"
+
+      config.info do
+        title       "Minha API"
+        version     "1.0.0"
+        description "Documentação da API gerada automaticamente"
+
+        contact do
+          name  "Minha equipe"
+          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         "https://api.mycompany.com"
+          description "Produção"
+        end
+
+        server do
+          url         "http://localhost:3000"
+          description "Desenvolvimento"
+        end
+      end
+
+      config.watch = :development  # recarrega automaticamente em mudanças de arquivo
+
+      # opcional: esquemas de segurança
+      config.security do
+        bearer_token format: "JWT"
+        api_key      name: "X-API-Key", in: :header
+      end
+    end
+    ```
+
+    Observações:
+    - A interface Swagger UI fornecida pela engine prioriza a origem atual da requisição (same-origin) como servidor primário para evitar problemas de CORS ao usar o recurso "Try it out". Você ainda pode listar outros servidores em `config.servers` apenas para fins informacionais; a UI buscará o documento OpenAPI a partir da URL do spec na mesma origem, construída automaticamente com o prefixo usado ao montar a engine.
+
+    ---
+
+    ## Uso
+
+    ### Criando uma classe OpenAPI
+
+    Crie um arquivo em `app/openapi/` seguindo a mesma convenção de nomes do ActiveModel::Serializer:
+
+    ```
+    app/
+      openapi/
+        user_openapi.rb     ->  User model
+        post_openapi.rb     ->  Post model
+        order_openapi.rb    ->  Order model
+    ```
+
+    ```ruby
+    # app/openapi/user_openapi.rb
+    class UserOpenapi < OpenapiBlocks::Base
+      # model User é inferido automaticamente a partir do nome da classe
+
+      # tags customizadas (padrão: inferido a partir do nome do controller/schema)
+      tags "Users"
+
+      # ignora campos sensíveis ou desnecessários
+      ignore :password_digest, :reset_password_token
+
+      # associações opt-in
+      association :company
+      association :posts, type: :array, input: false  # excluído do UserInput
+
+      # atributos virtuais (não existem no banco de dados)
+      # read_only: true  ->  exposto apenas na resposta (User)
+      # read_only: false ->  exposto em User e UserInput
+      attribute :full_name,    type: :string, read_only: true
+      attribute :access_token, type: :string, read_only: true
+      attribute :nickname,     type: :string
+    end
+    ```
+
+    ### O que é gerado automaticamente
+
+    Dado este model:
+
+    ```ruby
+    class User < ApplicationRecord
+      validates :name,  presence: true, length: { minimum: 2, maximum: 100 }
+      validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
+      validates :age,   numericality: { greater_than: 0 }
+      validates :role,  inclusion: { in: %w[admin user guest] }
+    end
+    ```
+
+    OpenapiBlocks gera:
+
+    - `User` schema a partir das colunas e tipos de `db/schema.rb`
+    - `UserInput` schema para bodies de request de `POST`, `PUT` e `PATCH` (sem `id`, `created_at`, `updated_at` e atributos virtuais marcados como `read_only`)
+    - campos `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`
+
+    ### Customizando operações
+
+    ```ruby
+    # app/openapi/user_openapi.rb
+    class UserOpenapi < OpenapiBlocks::Base
+      tags "Users"
+
+      operation :index do
+        summary     "List all users"
+        description "Returns a paginated list of active users"
+        tags        "Users", "Admin"  # sobrescreve tags em nível de operação
+
+        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 users", schema: { type: :array, items: :User }
+        response 401, description: "Unauthorized"
+      end
+
+      operation :show do
+        summary "Get a user"
+
+        response 200, description: "User found",     schema: :User
+        response 404, description: "User not found"
+      end
+
+      operation :create do
+        summary "Create a user"
+
+        response 201, description: "User created", schema: :User
+        response 422, description: "Invalid data"
+      end
+
+      operation :update do
+        summary "Update a user"
+
+        response 200, description: "User updated",   schema: :User
+        response 404, description: "User not found"
+        response 422, description: "Invalid data"
+      end
+
+      operation :destroy do
+        summary "Delete a user"
+
+        response 200, description: "User deleted"
+        response 404, description: "User not found"
+      end
+    end
+    ```
+
+    ---
+
+    ## Segurança
+
+    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>
+    end
+    ```
+
+    Substitua a segurança por operação:
+
+    ```ruby
+    operation :index do
+      security :bearerAuth   # apenas bearer nesta operação
+    end
+
+    operation :show do
+      no_security!           # endpoint público — sem autenticação
+    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, input: false   # excluído do UserInput (response only)
+    ```
+
+    ---
+
+    ## Atributos Virtuais
+
+    Atributos virtuais são campos que existem apenas na resposta da API e 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          |
+
+    ```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
+    ```
+
+    ---
+
+    ## 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                  |
+
+    ---
+
+    ## Auto-reload em desenvolvimento
+
+    OpenapiBlocks observa mudanças em:
+
+    ```
+    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.
+
+    ---
+
+    ## Requisitos
+
+    - Ruby >= 3.2
+    - Rails >= 7.0
+
+    ---
+
+    ## Licença
+
+    [MIT](LICENSE.txt)
+````

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/app/controllers/openapi_blocks/spec_controller.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "action_controller/api"
+
+module OpenapiBlocks
+  class SpecController < ActionController::API # rubocop:disable Style/Documentation
+    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"
+
+    def ui
+      render html: swagger_ui_html.html_safe
+    end
+
+    def show
+      spec = OpenapiBlocks::Builder.build.deep_stringify_keys
+      spec["servers"] = swagger_ui_servers(spec)
+
+      if request.format.yaml?
+        render plain: spec.to_yaml, content_type: "application/yaml"
+      else
+        render json: spec
+      end
+    end
+
+    private
+
+    def swagger_ui_html # rubocop:disable Metrics/MethodLength
+      urls = swagger_ui_urls
+
+      <<~HTML
+        <!doctype html>
+        <html lang="en">
+          <head>
+            <meta charset="utf-8" />
+            <meta name="viewport" content="width=device-width, initial-scale=1" />
+            <title>#{swagger_ui_title}</title>
+            <link rel="stylesheet" href="#{SWAGGER_UI_CSS}" />
+            <style>
+              html, body { margin: 0; padding: 0; height: 100%; background: #f6f7fb; }
+              #swagger-ui { height: 100%; }
+            </style>
+          </head>
+          <body>
+            <div id="swagger-ui"></div>
+            <script src="#{SWAGGER_UI_JS}"></script>
+            <script src="#{SWAGGER_UI_STANDALONE_JS}"></script>
+            <script>
+              window.ui = SwaggerUIBundle({
+                urls: #{urls.to_json},
+                'urls.primaryName': #{urls.first[:name].to_json},
+                dom_id: '#swagger-ui',
+                deepLinking: true,
+                displayRequestDuration: true,
+                docExpansion: 'list',
+                presets: [
+                  SwaggerUIBundle.presets.apis,
+                  SwaggerUIStandalonePreset
+                ],
+                layout: 'StandaloneLayout'
+              });
+            </script>
+          </body>
+        </html>
+      HTML
+    end
+
+    def swagger_ui_title
+      "#{OpenapiBlocks.configuration.info.title} - SwaggerUI"
+    end
+
+    def swagger_ui_urls # rubocop:disable Metrics/MethodLength
+      spec_base = swagger_spec_base_url
+      servers = OpenapiBlocks.configuration.to_h[:servers]
+
+      return default_swagger_ui_urls if servers.blank?
+
+      servers.flat_map do |server|
+        [
+          {
+            url:  "#{spec_base}.json",
+            name: "#{server[:url]} JSON"
+          },
+          {
+            url:  "#{spec_base}.yaml",
+            name: "#{server[:url]} YAML"
+          }
+        ]
+      end
+    end
+
+    def default_swagger_ui_urls
+      spec_base = swagger_spec_base_url
+
+      [
+        { url: "#{spec_base}.json", name: "OpenAPI JSON" },
+        { url: "#{spec_base}.yaml", name: "OpenAPI YAML" }
+      ]
+    end
+
+    def swagger_spec_base_url
+      mount_path = request.script_name.to_s.chomp("/")
+      mount_path.present? ? "#{mount_path}/openapi" : "/openapi"
+    end
+
+    def swagger_ui_servers(_spec)
+      [{ "url" => request.base_url, "description" => "Current" }]
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+OpenapiBlocks::Engine.routes.draw do
+  root to: "spec#ui"
+  get "openapi.json", to: "spec#show", defaults: { format: "json" }
+  get "openapi.yaml", to: "spec#show", defaults: { format: "yaml" }
+end

data/lib/openapi_blocks/base.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module OpenapiBlocks
+  class Base # rubocop:disable Style/Documentation
+    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, input: true)
+        @_associations ||= []
+        @_associations << { name: name, type: type, input: input }
+      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$/, "")
+                     .split("::")
+                     .last
+
+        Object.const_get(model_name)
+      rescue NameError
+        raise Error, "Could not infer model from #{name}. Use `model ModelClass` to define it explicitly."
+      end
+    end
+  end
+end

data/lib/openapi_blocks/builder.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "spec/document"
+
+module OpenapiBlocks
+  class Builder # rubocop:disable Style/Documentation
+    def self.build
+      new.build
+    end
+
+    def build
+      Spec::Document.new(openapi_classes).build
+    end
+
+    private
+
+    def openapi_classes
+      ObjectSpace.each_object(Class).select do |klass|
+        klass < OpenapiBlocks::Base
+      end
+    end
+  end
+end