docit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e48afeb14f8b73781bf089a31b30616c00d4aa053f079668fbecbc7215ea13e2
+  data.tar.gz: dd1ea68be0fb59dd014af55bb457fe110e2da2227fe56a0216d75c5051046215
+SHA512:
+  metadata.gz: ba5dadbd366f719b4420c515ad252380e4e5fd66137bb183e6b8d109426b0cf828eed12918658ea3a9af6e55d73f2c8e806e7a92c9d600d3a58e1fb643319576
+  data.tar.gz: 17690c65bec465a9b3479d80375a558a72bec94fd5677f8389e028d07d7b915e146bfa16b380ba0fb89aef33b848980033bcd38eb51ba04c6ef899c1c7c6663f

data/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,31 @@
+---
+name: Bug Report
+about: Report a bug to help us improve Docit
+labels: bug
+---
+
+## Description
+
+A clear and concise description of the bug.
+
+## Steps to Reproduce
+
+1. Configure Docit with `...`
+2. Add `swagger_doc` to `...`
+3. Visit `/api-docs`
+4. See error
+
+## Expected Behavior
+
+What you expected to happen.
+
+## Actual Behavior
+
+What actually happened. Include error messages or screenshots if applicable.
+
+## Environment
+
+- **Ruby version:**
+- **Rails version:**
+- **Docit version:**
+- **OS:**

data/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,27 @@
+---
+name: Feature Request
+about: Suggest a new feature for Docit
+labels: enhancement
+---
+
+## Description
+
+A clear and concise description of the feature you'd like.
+
+## Use Case
+
+Explain the problem this feature would solve or the workflow it would improve.
+
+## Proposed Solution
+
+Describe how you'd like it to work, including example DSL usage if applicable:
+
+```ruby
+swagger_doc :index do
+  # your proposed syntax here
+end
+```
+
+## Alternatives Considered
+
+Any alternative solutions or workarounds you've considered.

data/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,15 @@
+## What does this PR do?
+
+A brief description of the changes.
+
+## Related Issue
+
+Closes #
+
+## Checklist
+
+- [ ] Tests added/updated for the changes
+- [ ] All tests pass (`bundle exec rspec`)
+- [ ] No new linter warnings (`bundle exec rubocop`)
+- [ ] CHANGELOG.md updated (if user-facing change)
+- [ ] Documentation updated (if applicable)

data/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby-version: ["3.2", "3.3", "3.4"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby ${{ matrix.ruby-version }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true
+
+      - name: Run tests
+        run: bundle exec rspec
+
+      - name: Run linter
+        run: bundle exec rubocop

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-04-08
+
+- Initial release
+- DSL: `swagger_doc` macro for inline controller documentation
+- DSL: `use_docs` + `Docit::DocFile` for separate doc files (drf-spectacular style)
+- Builders: request body, response, and parameter builders with nested object/array support
+- Schema `$ref` components via `Docit.define_schema`
+- File upload support (`type: :file` → `string/binary`)
+- Configuration: auth schemes (bearer, basic, api_key), tag descriptions, server URLs
+- Rails Engine: Swagger UI at mounted path, JSON spec endpoint
+- Route introspection with eager-loading for development mode
+- Install generator: `rails g docit:install`
+- OpenAPI 3.0.3 spec generation

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,39 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or advances
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainers at siegdomain1@gmail.com. All complaints will
+be reviewed and investigated.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.0, available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.

data/CONTRIBUTING.md

@@ -0,0 +1,78 @@
+# Contributing to Docit
+
+Docit welcomes any form of contribution. Your contribution matters even if it is only a small one.
+
+Contributions come in different shapes and sizes:
+
+- Documentation improvements, clarifications & fixing typos
+- Creating issues for feature requests & bug reports
+- Creating pull requests for features and bug fixes
+- Questions that highlight inconsistencies or workflow issues
+- Adding support for additional authentication schemes or OpenAPI features
+
+## Issues
+
+Generating OpenAPI schemas from Rails controllers is subtle work — the devil often lies in the details. A concise description with examples goes a long way. If possible, please include:
+
+- A concise description of the problem
+- Example controller code that produces the issue
+- The generated (partial) OpenAPI spec showing the problem
+- Stacktraces if an error occurred
+- Docit / Ruby / Rails versions (`bundle show docit`, `ruby -v`, `rails -v`)
+
+## Pull requests
+
+Docit aims for high test coverage and an extensive test suite. Tests enable us to maintain quality, reliability, and consistency as the gem grows.
+
+- **Keep changes minimal.** Make the smallest invasive change that solves the problem. On receiving feedback, amend existing commits rather than adding fixup commits — use `git commit --amend` and `git push --force` to update your PR.
+- **Get early feedback on non-trivial PRs.** Open an issue first to discuss the approach. We don't want to waste anyone's time.
+- **Write tests.** Look at `spec/docit/` for unit test patterns and `spec/integration/` for engine tests. Small additions can go into `spec/docit/v2_features_spec.rb` or a new spec file for the feature.
+- **All tests must pass.** Your PR must pass the full suite to be merged.
+
+## Getting started
+
+```bash
+# Fork the repo on GitHub, then:
+git clone https://github.com/YOURGITHUBNAME/docit.git
+cd docit
+
+# Install dependencies
+bundle install
+
+# Run the test suite
+bundle exec rspec
+
+# Run a specific test file
+bundle exec rspec spec/docit/schema_generator_spec.rb
+
+# Run a single test by line number
+bundle exec rspec spec/docit/v2_features_spec.rb:30
+```
+
+## Project structure
+
+```
+lib/docit.rb                          # Entry point, configuration, schema registry
+lib/docit/configuration.rb            # Config class (title, auth, tags)
+lib/docit/registry.rb                 # Global operation store
+lib/docit/dsl.rb                      # swagger_doc macro
+lib/docit/operation.rb                # Single endpoint documentation
+lib/docit/builders/                   # DSL builders (response, request_body, parameter)
+lib/docit/schema_definition.rb        # Reusable $ref schema definitions
+lib/docit/schema_generator.rb         # Registry → OpenAPI 3.0.3 spec
+lib/docit/route_inspector.rb          # Rails route introspection
+lib/docit/engine.rb                   # Rails Engine (Swagger UI + spec endpoint)
+app/controllers/docit/ui_controller.rb # Serves Swagger UI and JSON spec
+lib/generators/docit/install/         # rails g docit:install generator
+spec/dummy/                            # Minimal Rails app for integration tests
+```
+
+## Code style
+
+- Follow existing patterns in the codebase
+- Use `frozen_string_literal: true` in all Ruby files
+- Prefer keyword arguments for clarity (`location:` instead of positional args)
+- Use `instance_eval(&block)` for DSL blocks
+- Return defensive copies (`.dup`) from accessor methods that expose internal state
+
+With that out of the way, we hope to hear from you soon.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 S13G
+
+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,416 @@
+# Docit
+
+[![Gem Version](https://badge.fury.io/rb/docit.svg)](https://rubygems.org/gems/docit)
+[![CI](https://github.com/S13G/docket/actions/workflows/ci.yml/badge.svg)](https://github.com/S13G/docket/actions/workflows/ci.yml)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.2-red.svg)](https://www.ruby-lang.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Decorator-style API documentation for Ruby on Rails. Write OpenAPI 3.0 docs as clean DSL macros directly on your controller actions: no separate doc files, no RSpec integration required. Just annotate and go.
+
+Inspired by [drf-spectacular](https://github.com/tfranzel/drf-spectacular) for Django REST Framework.
+
+## Installation
+
+Add Docit to your Gemfile:
+
+```ruby
+gem "docit"
+```
+
+Then run:
+
+```bash
+bundle install
+rails generate docit:install
+```
+
+The generator does two things:
+
+1. Creates `config/initializers/docit.rb` with default settings
+2. Mounts the Swagger UI engine at `/api-docs` in your routes
+
+Visit `/api-docs` to see your interactive API documentation.
+
+## Configuration
+
+Edit `config/initializers/docit.rb`:
+
+```ruby
+Docit.configure do |config|
+  config.title       = "My API"
+  config.version     = "1.0.0"
+  config.description = "Backend API documentation"
+
+  # Authentication: pick one (or multiple):
+  config.auth :bearer                              # Bearer token (JWT by default)
+  config.auth :basic                               # HTTP Basic
+  config.auth :api_key, name: "X-API-Key",         # API key in header
+                         location: "header"
+
+  # Tag descriptions (shown in Swagger UI sidebar):
+  config.tag "Users", description: "User account management"
+  config.tag "Auth",  description: "Authentication endpoints"
+
+  # Server URLs (shown in Swagger UI server dropdown):
+  config.server "https://api.example.com", description: "Production"
+  config.server "https://staging.example.com", description: "Staging"
+  config.server "http://localhost:3000", description: "Development"
+end
+```
+
+## Usage
+
+Docit supports two styles for documenting endpoints. Choose whichever fits your project or mix both.
+
+### Style 1: Inline (simple APIs)
+
+Add `swagger_doc` blocks directly in your controller:
+
+```ruby
+class Api::V1::UsersController < ApplicationController
+  swagger_doc :index do
+    summary "List all users"
+    tags "Users"
+    response 200, "Users retrieved"
+  end
+  def index
+    # your code
+  end
+end
+```
+
+### Style 2: Separate doc files (recommended for larger APIs)
+
+Keep controllers clean by defining docs in dedicated files, just like drf-spectacular:
+
+```ruby
+# app/docs/api/v1/users_docs.rb
+module Api::V1::UsersDocs
+  extend Docit::DocFile
+
+  doc :index do
+    summary "List all users"
+    description "Returns a paginated list of users"
+    tags "Users"
+
+    parameter :page, location: :query, type: :integer, description: "Page number"
+
+    response 200, "Users retrieved" do
+      property :users, type: :array, items: :object do
+        property :id, type: :integer, example: 1
+        property :email, type: :string, example: "user@example.com"
+      end
+      property :total, type: :integer, example: 42
+    end
+  end
+
+  doc :create do
+    summary "Create a user"
+    tags "Users"
+
+    request_body required: true do
+      property :email, type: :string, required: true
+      property :password, type: :string, required: true, format: :password
+    end
+
+    response 201, "User created" do
+      property :id, type: :integer
+    end
+
+    response 422, "Validation failed" do
+      property :errors, type: :object do
+        property :email, type: :array, items: :string
+      end
+    end
+  end
+end
+
+# app/controllers/api/v1/users_controller.rb — stays clean!
+class Api::V1::UsersController < ApplicationController
+  use_docs Api::V1::UsersDocs
+
+  def index
+    # pure business logic
+  end
+
+  def create
+    # pure business logic
+  end
+end
+```
+
+You can also mix both styles — use `use_docs` for most actions and add inline `swagger_doc` for one-offs:
+
+```ruby
+class Api::V1::UsersController < ApplicationController
+  use_docs Api::V1::UsersDocs        # loads :index and :create from doc file
+
+  swagger_doc :destroy do             # inline doc for this one action
+    summary "Delete user"
+    tags "Users"
+    response 204, "Deleted"
+  end
+
+  def index; end
+  def create; end
+  def destroy; end
+end
+```
+
+### Endpoint documentation DSL
+
+The following examples work in both `swagger_doc` blocks and `doc` blocks.
+
+### Request bodies
+
+```ruby
+swagger_doc :create do
+  summary "Create a user"
+  tags "Users"
+
+  request_body required: true do
+    property :email, type: :string, required: true, example: "user@example.com"
+    property :password, type: :string, required: true, format: :password
+    property :name, type: :string, example: "Jane Doe"
+    property :profile, type: :object do
+      property :bio, type: :string
+      property :avatar_url, type: :string, format: :uri
+    end
+  end
+
+  response 201, "User created" do
+    property :id, type: :integer, example: 1
+    property :email, type: :string, example: "user@example.com"
+  end
+
+  response 422, "Validation failed" do
+    property :errors, type: :object do
+      property :email, type: :array, items: :string
+    end
+  end
+end
+def create
+  # your code
+end
+```
+
+### Path parameters
+
+```ruby
+swagger_doc :show do
+  summary "Get a user"
+  tags "Users"
+
+  parameter :id, location: :path, type: :integer, required: true, description: "User ID"
+
+  response 200, "User found" do
+    property :id, type: :integer, example: 1
+    property :email, type: :string
+    property :name, type: :string
+  end
+
+  response 404, "User not found" do
+    property :error, type: :string, example: "Not found"
+  end
+end
+def show
+  # your code
+end
+```
+
+### Enums
+
+```ruby
+swagger_doc :index do
+  summary "List orders"
+  tags "Orders"
+
+  parameter :status, location: :query, type: :string,
+            enum: %w[pending shipped delivered],
+            description: "Filter by status"
+
+  response 200, "Orders list" do
+    property :orders, type: :array do
+      property :id, type: :integer
+      property :status, type: :string, enum: %w[pending shipped delivered]
+    end
+  end
+end
+```
+
+### Security
+
+Mark endpoints as requiring authentication:
+
+```ruby
+swagger_doc :destroy do
+  summary "Delete a user"
+  tags "Users"
+  security :bearer_auth      # references the scheme from your config
+
+  response 204, "User deleted"
+  response 401, "Unauthorized"
+end
+```
+
+### Deprecated endpoints
+
+```ruby
+swagger_doc :legacy_search do
+  summary "Search (legacy)"
+  tags "Search"
+  deprecated
+
+  response 200, "Results"
+end
+```
+
+### Nested objects and arrays
+
+```ruby
+response 200, "Success" do
+  property :user, type: :object do
+    property :id, type: :integer
+    property :name, type: :string
+    property :addresses, type: :array do
+      property :street, type: :string
+      property :city, type: :string
+      property :zip, type: :string
+    end
+  end
+end
+```
+
+### Response examples
+
+```ruby
+response 200, "User found" do
+  property :id, type: :integer
+  property :email, type: :string
+
+  example "admin_user",
+          { id: 1, email: "admin@example.com" },
+          description: "An admin user"
+
+  example "regular_user",
+          { id: 2, email: "user@example.com" },
+          description: "A regular user"
+end
+```
+
+### Shared schemas (`$ref`)
+
+Define reusable schemas once and reference them across multiple endpoints:
+
+```ruby
+# In config/initializers/docit.rb or a dedicated file:
+Docit.define_schema :User do
+  property :id,    type: :integer, example: 1
+  property :email, type: :string,  example: "user@example.com"
+  property :name,  type: :string,  example: "Jane Doe"
+  property :address, type: :object do
+    property :street, type: :string
+    property :city,   type: :string
+  end
+end
+
+Docit.define_schema :Error do
+  property :error,   type: :string, example: "Not found"
+  property :details, type: :array, items: :string
+end
+```
+
+Reference them in any endpoint with `schema ref:`:
+
+```ruby
+swagger_doc :show do
+  summary "Get user"
+  tags "Users"
+
+  response 200, "User found" do
+    schema ref: :User
+  end
+
+  response 404, "Not found" do
+    schema ref: :Error
+  end
+end
+
+swagger_doc :create do
+  summary "Create user"
+  tags "Users"
+
+  request_body required: true do
+    schema ref: :User
+  end
+
+  response 201, "Created" do
+    schema ref: :User
+  end
+end
+```
+
+This outputs `$ref: '#/components/schemas/User'` in the spec — Swagger UI resolves it automatically.
+
+### File uploads
+
+Use `type: :file` with `content_type: "multipart/form-data"` for file upload endpoints:
+
+```ruby
+swagger_doc :upload_avatar do
+  summary "Upload avatar"
+  tags "Users"
+
+  request_body required: true, content_type: "multipart/form-data" do
+    property :avatar, type: :file, required: true, description: "Avatar image"
+    property :caption, type: :string
+  end
+
+  response 201, "Avatar uploaded" do
+    property :url, type: :string, format: :uri
+  end
+end
+```
+
+`type: :file` maps to `{ type: "string", format: "binary" }` in the OpenAPI spec.
+
+## How it works
+
+1. `swagger_doc` registers an **Operation** for each controller action in a global **Registry**
+2. When someone visits `/api-docs/spec`, Docit's **SchemaGenerator** combines all registered operations with your Rails routes (via **RouteInspector**) to produce an OpenAPI 3.0.3 JSON document
+3. The **Engine** serves Swagger UI at `/api-docs`, pointing it at the generated spec
+
+The DSL is included in all controllers automatically via a Rails Engine initializer — no manual `include` needed if you're using `ActionController::API` or `ActionController::Base`.
+
+## Mounting at a different path
+
+In `config/routes.rb`:
+
+```ruby
+mount Docit::Engine => "/docs"        # now at /docs instead of /api-docs
+```
+
+## JSON spec only
+
+If you just want the raw OpenAPI JSON (e.g., for code generation):
+
+```
+GET /api-docs/spec
+```
+
+## Development
+
+```bash
+git clone https://github.com/S13G/docket.git
+cd docit
+bundle install
+bundle exec rspec        # run all tests
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/S13G/docket).
+
+## License
+
+[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]