openapi_blocks 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 955300fe20fc1f9dfe45283d0f4608886592feceb45db0cb7765e7eac1bda439
+  data.tar.gz: bcac14db5aae2164a71ec642cea311aeba135c3f7f43d3a173aea92579cedbcb
+SHA512:
+  metadata.gz: 6be97c3ea397aafdc76b6f51f9222cc6bf2cfd0b8ef76982ce7cc73a79687f095110f99902cb8be787c3b1603bc9bdc47eb7ae14a2fab7fbfe24fd4fb71db4ad
+  data.tar.gz: e2b44b0e135fefd0c1af80a86c76dd2cfbc7cc69d9c74de0821808cf75ce4945cdf5e18ca4c1a55e95a096ab404255a0e4c6213e0227b5aac2be0a9777e9745c

data/CHANGELOG.md

@@ -0,0 +1,86 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-06-01
+
+### Added
+
+- `OpenapiBlocks::OperationBuilder` DSL for customizing operations per action
+- `summary` and `description` customization per operation
+- `parameter` DSL for query parameters with `in:`, `type:`, `description:` and `required:` options
+- `response` DSL with `description:` and `schema:` options
+- `tags` DSL on `OpenapiBlocks::Base` for custom tags per OpenAPI class
+- `tags` DSL on `OperationBuilder` for custom tags per operation
+- Tag resolution priority: operation tags > class tags > inferred from controller name
+- `OpenapiBlocks::Configuration::SecurityBuilder` with `bearer_token` and `api_key` DSL
+- Global `security` configuration in initializer
+- Per-operation `security` and `no_security!` DSL in `OperationBuilder`
+- `securitySchemes` generated automatically in `components`
+- `tags` array generated at document root level from paths
+- Swagger UI served at root of mounted engine (`/docs`)
+- `SpecController#ui` action serving Swagger UI with JSON/YAML spec switcher
+- `association` DSL now supports `input: false` to exclude from input schema
+- Associations excluded from `required` fields automatically
+- `resolve_schema` classifies symbol references (`:user` → `User`)
+- Automatic `UserInput` schema excludes `read_only: true` virtual attributes
+- Validation for `openapi_version` — raises `ArgumentError` for unsupported versions
+- RSpec coverage for `OperationBuilder`, `SecurityBuilder`, tags and security
+
+### Fixed
+
+- `find_openapi_class` uses `Object.const_get` instead of `ObjectSpace` for reliability
+- `openapi` version field correctly outputs `3.1.0` instead of `3.1`
+
+## [0.1.0] - 2026-06-01
+
+### Added
+
+- Initial project structure with gemspec, RSpec and RuboCop setup (`71be639`)
+- `OpenapiBlocks::Configuration` with DSL for `info`, `servers` and `openapi_version` (3.0 / 3.1)
+- `OpenapiBlocks::Cache` thread-safe in-memory cache with `Mutex`
+- `OpenapiBlocks::FileWatcher` monitoring `app/openapi`, `app/models`, `config/routes.rb` and `db/schema.rb`
+- `OpenapiBlocks::Middleware` with automatic cache invalidation on file changes
+- `OpenapiBlocks::Railtie` for automatic middleware injection and eager loading of `app/openapi` (`28d9cab`)
+- `OpenapiBlocks::Schema::Extractor` for automatic schema generation from ActiveRecord columns
+- `OpenapiBlocks::Schema::Validator` for mapping ActiveModel validations to OpenAPI restrictions (`minLength`, `maxLength`, `minimum`, `maximum`, `enum`, `pattern`, `format`)
+- `OpenapiBlocks::Schema::Types` mapping ActiveRecord types to OpenAPI types (`1256d31`)
+- `OpenapiBlocks::Routing::Operation` and `OpenapiBlocks::Routing::Extractor` for automatic path generation from Rails routes
+- `OpenapiBlocks::Spec::Document`, `OpenapiBlocks::Spec::Paths` and `OpenapiBlocks::Spec::Components` for OpenAPI document assembly
+- `OpenapiBlocks::Builder` for orchestrating spec generation (`db5910a`)
+- `OpenapiBlocks::Engine` mountable in `config/routes.rb` exposing `/openapi.json` and `/openapi.yaml`
+- `OpenapiBlocks::SpecController` replacing previous implementation (`cbacd18`)
+- Automatic `UserInput` schema generation for `POST`, `PUT` and `PATCH` request bodies
+- Validation merging into schema properties
+- Automatic filtering of internal Rails routes (`rails/`, `action_mailbox/`, `active_storage/`) (`35737ab`)
+- `OpenapiBlocks::OperationBuilder` DSL for customizing operations per action (`operation :index`, `:show`, `:create`, `:update`, `:destroy`)
+- `summary` and `description` customization per operation
+- `parameter` DSL for query parameters with `in:`, `type:`, `description:` and `required:` options
+- `response` DSL for custom responses with `description:` and `schema:` options
+- Schema resolution supporting `Symbol` (`schema: :User`) and array (`schema: { type: :array, items: :User }`) references
+- Fallback to auto-generated responses when no custom `operation` block is defined (`0055aa3`)
+- RSpec coverage for `Schema::Types`, `Schema::Validator`, `Schema::Extractor`, `Routing::Extractor`, `Spec::Components` and `Configuration`
+- Validation for `openapi_version` — raises `ArgumentError` for unsupported versions
+- `read_only: true` virtual attributes excluded from `UserInput` schema
+- `OpenapiBlocks::Configuration::SecurityBuilder` with `bearer_token` and `api_key` DSL
+- Global `security` configuration in initializer
+- Per-operation `security` and `no_security!` DSL in `OperationBuilder`
+- `securitySchemes` generated automatically in `components`
+- `tags` array generated at document root level from paths
+- `association` DSL now supports `input: false` to exclude from `UserInput`
+- Associations excluded from `required` fields automatically
+- `resolve_schema` now classifies symbol references (`:user` → `User`)
+- `tags` DSL on `OpenapiBlocks::Base` for custom tags per OpenAPI class
+- `tags` DSL on `OperationBuilder` for custom tags per operation
+- Tag resolution priority: operation tags > class tags > inferred from controller name
+- Swagger UI served at root of mounted engine (`/docs`)
+- `SpecController#ui` action serving Swagger UI with JSON/YAML spec switcher
+
+[Unreleased]: https://github.com/evotechbuilder/openapi_blocks/compare/v0.2.0...HEAD
+[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/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"openapi_blocks" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["caio.francelinosena@gmail.com"](mailto:"caio.francelinosena@gmail.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Caio Santos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,304 @@
+# 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).
+
+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.
+
+---
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "openapi_blocks"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+---
+
+## Setup
+
+### 1. Mount the Engine
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  mount OpenapiBlocks::Engine => "/docs"
+
+  resources :users
+end
+```
+
+This exposes:
+
+```
+GET /docs               ->  Swagger UI
+GET /docs/openapi.json  ->  OpenAPI spec in JSON
+GET /docs/openapi.yaml  ->  OpenAPI spec in YAML
+```
+
+### 2. Configure the initializer
+
+```ruby
+# config/initializers/openapi_blocks.rb
+OpenapiBlocks.configure do |config|
+  config.openapi_version = "3.1"  # "3.0" or "3.1"
+
+  config.info do
+    title       "My API"
+    version     "1.0.0"
+    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         "https://api.mycompany.com"
+      description "Production"
+    end
+
+    server do
+      url         "http://localhost:3000"
+      description "Development"
+    end
+  end
+
+  config.watch = :development  # auto-reload on file changes
+
+  # optional: security schemes
+  config.security do
+    bearer_token format: "JWT"
+    api_key      name: "X-API-Key", in: :header
+  end
+end
+```
+
+---
+
+## Usage
+
+### Creating an OpenAPI class
+
+Create a file in app/openapi/ following the same naming convention as 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 is inferred automatically from the class name
+
+  # custom tags (default: inferred from controller name)
+  tags "Users"
+
+  # opt-out sensitive or unnecessary fields
+  ignore :password_digest, :reset_password_token
+
+  # opt-in associations
+  association :company
+  association :posts, type: :array, input: false  # excluded from UserInput
+
+  # virtual attributes (not in the database)
+  # read_only: true  ->  exposed in response (User), excluded from request body (UserInput)
+  # read_only: false ->  exposed in both User and UserInput
+  attribute :full_name,    type: :string, read_only: true
+  attribute :access_token, type: :string, read_only: true
+  attribute :nickname,     type: :string
+end
+```
+
+### What is generated automatically
+
+Given this 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 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 virtual attributes)
+- 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
+
+### Customizing operations
+
+```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"  # overrides class-level tags for this operation
+
+    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
+```
+
+---
+
+## Security
+
+Configure global security schemes in the initializer:
+
+```ruby
+config.security do
+  bearer_token format: "JWT"                    # Authorization: Bearer <token>
+  api_key      name: "X-API-Key", in: :header   # X-API-Key: <key>
+end
+```
+
+Override security per operation:
+
+```ruby
+operation :index do
+  security :bearerAuth   # only bearer on this operation
+end
+
+operation :show do
+  no_security!           # public endpoint — no auth required
+end
+```
+
+---
+
+## Associations
+
+```ruby
+association :company                             # belongs_to — $ref to Company schema
+association :posts, type: :array                 # has_many — array of $ref to Post schema
+association :posts, type: :array, input: false   # excluded from UserInput (response only)
+```
+
+---
+
+## Virtual Attributes
+
+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          |
+
+```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
+```
+
+---
+
+## 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             |
+
+---
+
+## Auto-reload in Development
+
+OpenapiBlocks watches for changes in:
+
+```
+app/openapi/**/*.rb
+app/models/**/*.rb
+config/routes.rb
+db/schema.rb
+```
+
+The spec is automatically regenerated on the next request to /docs/openapi.json whenever any of these files change. No server restart needed.
+
+---
+
+## Requirements
+
+- Ruby >= 3.2
+- Rails >= 7.0
+
+---
+
+## License
+
+MIT (LICENSE.txt)