docit 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 19ca1ea84419aa3ec1c1605fec67c6355027d866de1b9e6b0d8fb27472b91602
-  data.tar.gz: a8fc557d32361a3729a9133791100bea3c7bf94e4c2f0ca55351eff4760efafe
+  metadata.gz: 39589c6800b65d7a0ad55701378b345f18277735df3511cce965bc889035e74f
+  data.tar.gz: 91c392bded5bbd0897222859feab4d68e8c0d3064d4054e6b75509a325ced2d0
 SHA512:
-  metadata.gz: 4614b2cc382920b578400ddbccb8afb0eb8a32830307e0fd75fc3a175678f218d7f658e82b61678422d520c6f6c841fa5643d36d563b6cacf0bd4233bbed655f
-  data.tar.gz: fe46a50539ba08a2783b8e1f4d95a2e313fc1a043f78dee017ad4dd47cba8166f5cb8341bf5cbf732b4e7f7a776e9966e12efcce4c1a1b3a3b2c08cf2887acf1
+  metadata.gz: 1ea253c903e6a90eb3754ed9f4a586adcc7339c831d9623401cc4bb53256359c81e069bba4067a12379da350fbf354b50bfd14420ae0aa75c3841c74942ae5f2
+  data.tar.gz: 8441b41ae22a25f1bd29514fbdcb425b4bbd56b591da6904df0c9ad070a7ac830b1eb9338783a8c751d8f648db4826d69b7755a0f42cd320baaf8e3ebeb7c628

data/.github/ISSUE_TEMPLATE/bug_report.md

@@ -11,7 +11,7 @@ A clear and concise description of the bug.
 ## Steps to Reproduce
 
 1. Configure Docit with `...`
-2. Add `swagger_doc` to `...`
+2. Add `doc_for` to `...`
 3. Visit `/api-docs`
 4. See error
 

data/.github/ISSUE_TEMPLATE/feature_request.md

@@ -17,7 +17,7 @@ Explain the problem this feature would solve or the workflow it would improve.
 Describe how you'd like it to work, including example DSL usage if applicable:
 
 ```ruby
-swagger_doc :index do
+doc_for :index do
   # your proposed syntax here
 end
 ```

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 ## [Unreleased]
 
+## [0.4.0] - 2026-04-18
+
+### Added
+- `operation_id` DSL method: set a custom `operationId` per endpoint for cleaner SDK codegen
+- Auto-generated `operationId` for every endpoint (e.g., `index_users`, `login_auth`) when not explicitly set
+- `config.license` option: add license info (`name`, `url`) to the OpenAPI spec
+- `config.contact` option: add contact info (`name`, `email`, `url`) to the OpenAPI spec
+- `config.terms_of_service` option: add terms of service URL to the OpenAPI spec
+
+### Changed
+- Renamed `swagger_doc` DSL to `doc_for` (`swagger_doc` still works as a backward-compatible alias)
+
+### Fixed
+- `TagInjector` no longer crashes when `initializer_path` is nil
+- `docit:autodoc` rake task: removed broken `--dry-run` CLI flag (use `DRY_RUN=1` env var instead)
+- Fixed dummy app `auth_docs.rb` summary and request body to match integration test expectations
+
+## [0.3.1] - 2026-04-17
+
+### Fixed
+- Fixed gem packaging: `doc_block_validator.rb` was missing from the published 0.3.0 gem, causing `LoadError` on require
+
 ## [0.3.0] - 2026-04-16
 
 ### Added
@@ -51,7 +73,7 @@
 ## [0.1.0] - 2026-04-08
 
 - Initial release
-- DSL: `swagger_doc` macro for inline controller documentation
+- DSL: `doc_for` macro for inline controller documentation
 - DSL: `use_docs` + `Docit::DocFile` for separate doc files
 - Builders: request body, response, and parameter builders with nested object/array support
 - Schema `$ref` components via `Docit.define_schema`

data/CONTRIBUTING.md

@@ -55,7 +55,7 @@ bundle exec rspec spec/docit/v2_features_spec.rb:30
 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/dsl.rb                      # doc_for 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

data/README.md

@@ -5,44 +5,13 @@
 
 Decorator-style API documentation for Ruby on Rails. Write OpenAPI 3.0.3 docs with clean controller DSL macros, separate doc modules, or AI-assisted scaffolding for undocumented endpoints.
 
-## Table Of Contents
-
-- Getting started
-  - [Installation](#installation)
-  - [Configuration](#configuration)
-  - [Usage](#usage)
-- Documentation styles
-  - [Style 1: Inline (simple APIs)](#style-1-inline-simple-apis)
-  - [Style 2: Separate doc files (recommended for larger APIs)](#style-2-separate-doc-files-recommended-for-larger-apis)
-- Endpoint DSL reference
-  - [Endpoint documentation DSL](#endpoint-documentation-dsl)
-  - [Request bodies](#request-bodies)
-  - [Path parameters](#path-parameters)
-  - [Enums](#enums)
-  - [Security](#security)
-  - [Deprecated endpoints](#deprecated-endpoints)
-  - [Nested objects and arrays](#nested-objects-and-arrays)
-  - [Response examples](#response-examples)
-  - [Shared schemas (`$ref`)](#shared-schemas-ref)
-  - [File uploads](#file-uploads)
-- AI documentation
-  - [AI Automatic Documentation](#ai-automatic-documentation)
-  - [Quick start (included in install)](#quick-start-included-in-install)
-  - [Standalone commands](#standalone-commands)
-  - [Supported providers](#supported-providers)
-  - [What the AI generates](#what-the-ai-generates)
-- Runtime and development
-  - [Documentation UIs](#documentation-uis)
-  - [How it works](#how-it-works)
-  - [Mounting at a different path](#mounting-at-a-different-path)
-  - [JSON spec only](#json-spec-only)
-  - [Development](#development)
-  - [Contributing](#contributing)
-  - [License](#license)
-- Project docs
-  - [CHANGELOG](CHANGELOG.md)
-  - [CONTRIBUTING](CONTRIBUTING.md)
-  - [CODE OF CONDUCT](CODE_OF_CONDUCT.md)
+### Scalar (default)
+![Scalar API Reference](docs/images/scalar_image.png)
+
+### Swagger
+![Swagger UI](docs/images/swagger_image.png)
+
+> **Full documentation:** [docitruby.dev/docs](https://docitruby.dev/docs)
 
 ## Installation
 
@@ -70,8 +39,6 @@ The install generator does everything in one step:
 
 Visit `/api-docs` to see your interactive API documentation (Scalar by default, Swagger UI also available at `/api-docs/swagger`).
 
-If you choose AI setup, Docit stores your provider config in `.docit_ai.yml` with restricted file permissions and adds that file to `.gitignore` when possible.
-
 ## Configuration
 
 Edit `config/initializers/docit.rb`:
@@ -81,48 +48,40 @@ Docit.configure do |config|
   config.title       = "My API"
   config.version     = "1.0.0"
   config.description = "Backend API documentation"
+  config.default_ui  = :scalar    # :scalar (default) or :swagger
 
-  # Documentation UI: :scalar (default) or :swagger
-  config.default_ui  = :scalar
-
-  # 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 the documentation sidebar):
+  config.auth :bearer              # Bearer token (JWT)
   config.tag "Users", description: "User account management"
-  config.tag "Auth",  description: "Authentication endpoints"
-
-  # Server URLs (shown in the 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
+See the [full configuration reference](https://docitruby.dev/docs/configuration) for all options including `license`, `contact`, `terms_of_service`, multiple auth schemes, and server URLs.
+
+## Quick Start
 
-Docit supports two styles for documenting endpoints. Choose whichever fits your project or mix both.
+Docit supports two styles. Choose whichever fits your project or mix both.
 
 ### Style 1: Inline (simple APIs)
 
-Add `swagger_doc` blocks directly in your controller:
+Add `doc_for` blocks directly in your controller:
 
 ```ruby
 class Api::V1::UsersController < ApplicationController
-  swagger_doc :index do
+  doc_for :index do
     summary "List all users"
     tags "Users"
     response 200, "Users retrieved"
   end
+
   def index
     # your code
   end
 end
 ```
 
+> **Upgrading?** The previous `swagger_doc` method still works as an alias for `doc_for`, so existing code won't break.
+
 ### Style 2: Separate doc files (recommended for larger APIs)
 
 Keep controllers clean by defining docs in dedicated files:
@@ -134,387 +93,70 @@ module Api::V1::UsersDocs
 
   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!
+```ruby
+# app/controllers/api/v1/users_controller.rb
 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.
-
-## AI Automatic Documentation
-
-Docit can generate complete API documentation using AI. This works with OpenAI, Anthropic, or Groq (free tier available).
+See the [full DSL reference](https://docitruby.dev/docs/dsl-reference) for request bodies, path parameters, enums, security, nested objects, file uploads, shared schemas, and more.
 
-### Quick start (included in install)
+## AI Documentation
 
-When you run `rails generate docit:install` and choose option 1 (AI automatic docs), everything is set up automatically — provider configuration, doc generation, controller wiring, and tag injection.
+Docit can generate complete API documentation using AI. Works with OpenAI, Anthropic, or Groq (free tier available).
 
-Before the first AI request, Docit warns that your controller source code will be sent to the selected provider and asks for confirmation in interactive terminals.
-
-### Standalone commands
-
-You can also set up AI docs separately:
+When you run `rails generate docit:install` and choose AI automatic docs, everything is set up automatically — provider configuration, doc generation, controller wiring, and tag injection.
 
 ```bash
-# Configure your AI provider (one-time setup)
+# Or set up AI docs separately:
 rails generate docit:ai_setup
-
-# Generate docs for all undocumented endpoints
 rails docit:autodoc
 
-# Generate docs for a specific controller
-rails docit:autodoc[Api::V1::UsersController]
-
-# Preview what would be generated without writing files
+# Preview without writing files:
 DRY_RUN=1 rails docit:autodoc
 ```
 
-### Supported providers
-
-| Provider   | Notes |
-|------------|-------|
-| OpenAI     | Requires API key from platform.openai.com |
-| Anthropic  | Requires API key from console.anthropic.com |
-| Groq       | Free tier at console.groq.com |
-
-All providers automatically retry on rate-limit (429) errors with exponential backoff, so free-tier usage works out of the box.
-
-AI configuration is stored in `.docit_ai.yml`.
-If your app does not have a `.gitignore`, add `.docit_ai.yml` manually.
-
-### What the AI generates
-
-For each undocumented endpoint, Docit:
-
-1. Reads the controller source code
-2. Inspects the route (HTTP method, path, parameters)
-3. Writes the generated doc block to `app/docs/`
-4. Injects `use_docs` into the controller
-5. Adds tag descriptions to the initializer
-
-Do not use AI autodoc on controllers that contain secrets, proprietary business rules, or internal comments you do not want sent to an external provider.
+See the [full AI documentation guide](https://docitruby.dev/docs/ai-documentation) for provider details, safety considerations, and standalone commands.
 
 ## Documentation UIs
 
-Docit ships with two documentation UIs, both reading from the same OpenAPI spec:
-
 | Path | UI | Notes |
 |------|------|-------|
 | `/api-docs` | Default (Scalar) | Configurable via `config.default_ui` |
-| `/api-docs/scalar` | Scalar API Reference | Modern UI with built-in API client, dark mode, code samples |
+| `/api-docs/scalar` | Scalar API Reference | Modern UI with API client, dark mode |
 | `/api-docs/swagger` | Swagger UI | Classic OpenAPI explorer |
 | `/api-docs/spec` | Raw JSON | OpenAPI 3.0.3 spec |
 
-Both UIs include a navigation bar to switch between them. Set `config.default_ui = :swagger` to make Swagger the default at `/api-docs`.
-
-## How it works
+## How It Works
 
-1. `swagger_doc` registers an **Operation** for each controller action in a global **Registry**
+1. `doc_for` 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 the configured documentation 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/docit.git
 cd docit
 bundle install
-bundle exec rspec        # run all tests
+bundle exec rspec
 ```
 
 ## Contributing

data/lib/docit/ai/autodoc_runner.rb

@@ -62,11 +62,11 @@ module Docit
         end
 
         routes_file = Rails.root.join("config", "routes.rb")
-        if File.exist?(routes_file) && !File.read(routes_file).include?("Docit::Engine")
-          @output.puts "Warning: Docit engine is not mounted in config/routes.rb"
-          @output.puts "  Run: rails generate docit:install (or add: mount Docit::Engine => \"/api-docs\")"
-          @output.puts ""
-        end
+        return unless File.exist?(routes_file) && !File.read(routes_file).include?("Docit::Engine")
+
+        @output.puts "Warning: Docit engine is not mounted in config/routes.rb"
+        @output.puts "  Run: rails generate docit:install (or add: mount Docit::Engine => \"/api-docs\")"
+        @output.puts ""
       end
 
       def detect_gaps
@@ -84,20 +84,20 @@ module Docit
         @output.puts "Docit will send controller source code to #{config.provider.capitalize} to generate documentation."
         @output.puts "Review the endpoints first if they contain secrets or proprietary logic."
 
-        if @input.respond_to?(:tty?) && @input.tty?
-          loop do
-            @output.print "Continue? (y/n): "
-            choice = @input.gets.to_s.strip.downcase
-
-            case choice
-            when "y", "yes"
-              @output.puts ""
-              return
-            when "n", "no"
-              raise Docit::Error, "Autodoc cancelled."
-            else
-              @output.puts "Please enter y or n."
-            end
+        return unless @input.respond_to?(:tty?) && @input.tty?
+
+        loop do
+          @output.print "Continue? (y/n): "
+          choice = @input.gets.to_s.strip.downcase
+
+          case choice
+          when "y", "yes"
+            @output.puts ""
+            return
+          when "n", "no"
+            raise Docit::Error, "Autodoc cancelled."
+          else
+            @output.puts "Please enter y or n."
           end
         end
       end
@@ -138,6 +138,7 @@ module Docit
             invalid_output_retries += 1
             if invalid_output_retries <= MAX_INVALID_OUTPUT_RETRIES
               validation_error = e.message
+              @output.puts " invalid output, retrying"
               retry
             end
 
@@ -184,11 +185,11 @@ module Docit
 
       def inject_tags(generated)
         all_tags = generated.values.flatten.join("\n").scan(/tags\s+["']([^"']+)["']/).flatten
-        if all_tags.any?
-          injected = TagInjector.new(tags: all_tags).inject
-          injected.each { |tag| @output.puts "  Added tag \"#{tag}\" to config/initializers/docit.rb" }
-          @results[:tags] = injected
-        end
+        return unless all_tags.any?
+
+        injected = TagInjector.new(tags: all_tags).inject
+        injected.each { |tag| @output.puts "  Added tag \"#{tag}\" to config/initializers/docit.rb" }
+        @results[:tags] = injected
       end
 
       def strip_markdown_fences(text)

data/lib/docit/ai/doc_block_validator.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Docit
+  module Ai
+    class InvalidDocBlockError < Error; end
+
+    class DocBlockValidator
+      def initialize(controller:, action:, doc_block:)
+        @controller = controller
+        @action = action.to_sym
+        @doc_block = doc_block
+      end
+
+      def validate!
+        doc_module = Module.new
+        doc_module.extend(Docit::DocFile)
+        doc_module.module_eval(@doc_block, "(generated Docit block)", 1)
+
+        validate_actions!(doc_module.actions)
+
+        operation = Docit::Operation.new(controller: @controller, action: @action)
+        operation.instance_eval(&doc_module[@action])
+
+        true
+      rescue SyntaxError, StandardError => e
+        raise InvalidDocBlockError, error_message_for(e)
+      end
+
+      private
+
+      def validate_actions!(actions)
+        return if actions == [@action]
+
+        raise InvalidDocBlockError, "Generated output did not define a doc block" if actions.empty?
+
+        action_list = actions.map { |action| ":#{action}" }.join(", ")
+        raise InvalidDocBlockError,
+              "Generated output must define only doc :#{@action}, got #{action_list}"
+      end
+
+      def error_message_for(error)
+        return error.message if error.is_a?(InvalidDocBlockError)
+
+        "#{error.class}: #{error.message}"
+      end
+    end
+  end
+end

data/lib/docit/ai/tag_injector.rb

@@ -8,7 +8,7 @@ module Docit
       end
 
       def inject
-        return [] if initializer_path && File.exist?(initializer_path) == false
+        return [] unless initializer_path && File.exist?(initializer_path)
 
         content = File.read(initializer_path)
         existing_tags = content.scan(/config\.tag\s+["']([^"']+)["']/).flatten

data/lib/docit/configuration.rb

@@ -17,6 +17,9 @@ module Docit
       @security_schemes = {}
       @tags = []
       @servers = []
+      @license = nil
+      @contact = nil
+      @terms_of_service = nil
     end
 
     def default_ui=(value)
@@ -75,5 +78,35 @@ module Docit
     def servers
       @servers.dup
     end
+
+    def license(name:, url: nil)
+      entry = { name: name }
+      entry[:url] = url if url
+      @license = entry
+    end
+
+    def license_info
+      @license&.dup
+    end
+
+    def contact(name: nil, email: nil, url: nil)
+      entry = {}
+      entry[:name] = name if name
+      entry[:email] = email if email
+      entry[:url] = url if url
+      @contact = entry
+    end
+
+    def contact_info
+      @contact&.dup
+    end
+
+    def terms_of_service(url)
+      @terms_of_service = url
+    end
+
+    def terms_of_service_url
+      @terms_of_service
+    end
   end
 end

data/lib/docit/doc_file.rb

@@ -40,7 +40,7 @@ module Docit
       base.instance_variable_set(:@_docs, {})
     end
 
-    # The block receives the same DSL as swagger_doc.
+    # The block receives the same DSL as doc_for.
     def doc(action, &block)
       @_docs[action.to_sym] = block
     end

data/lib/docit/dsl.rb

@@ -2,14 +2,14 @@
 
 module Docit
   # Included in all Rails controllers via the Engine.
-  # Provides +swagger_doc+ and +use_docs+ class methods.
+  # Provides +doc_for+ and +use_docs+ class methods.
   module DSL
     def self.included(base)
       base.extend(ClassMethods)
     end
 
     module ClassMethods
-      def swagger_doc(action, &block)
+      def doc_for(action, &block)
         operation = Operation.new(
           controller: name,
           action: action
@@ -18,9 +18,12 @@ module Docit
         Registry.register(operation)
       end
 
+      # Backward-compatible alias
+      alias swagger_doc doc_for
+
       def use_docs(doc_module)
         doc_module.actions.each do |action|
-          swagger_doc(action, &doc_module[action])
+          doc_for(action, &doc_module[action])
         end
       end
     end

data/lib/docit/operation.rb

@@ -2,11 +2,11 @@
 
 module Docit
   # Represents the documentation for a single controller action.
-  # Created by +swagger_doc+ and stored in the {Registry}.
+  # Created by +doc_for+ and stored in the {Registry}.
   class Operation
     attr_reader :controller, :action, :_summary, :_description,
                 :_tags, :_responses, :_request_body, :_parameters,
-                :_security, :_deprecated
+                :_security, :_deprecated, :_operation_id
 
     def initialize(controller:, action:)
       @controller = controller
@@ -17,6 +17,7 @@ module Docit
       @_request_body = nil
       @_security = []
       @_deprecated = false
+      @_operation_id = nil
     end
 
     def summary(text)
@@ -35,6 +36,10 @@ module Docit
       @_deprecated = value
     end
 
+    def operation_id(text)
+      @_operation_id = text
+    end
+
     def security(scheme)
       @_security << scheme
     end

data/lib/docit/route_inspector.rb

@@ -5,7 +5,7 @@ module Docit
   class RouteInspector
     VALID_METHODS = %w[get post put patch delete].freeze
 
-    # Eagerly loads controller classes so swagger_doc/use_docs macros run before spec generation.
+    # Eagerly loads controller classes so doc_for/use_docs macros run before spec generation.
     def self.eager_load_controllers!
       return if defined?(Rails).nil? || Rails.application.routes.nil?
 

data/lib/docit/schema_generator.rb

@@ -12,11 +12,7 @@ module Docit
 
       spec = {
         openapi: "3.0.3",
-        info: {
-          title: config.title,
-          version: config.version,
-          description: config.description
-        },
+        info: build_info(config),
         paths: build_paths,
         components: {
           securitySchemes: config.security_schemes
@@ -37,6 +33,18 @@ module Docit
 
     private
 
+    def build_info(config)
+      info = {
+        title: config.title,
+        version: config.version,
+        description: config.description
+      }
+      info[:license] = config.license_info if config.license_info
+      info[:contact] = config.contact_info if config.contact_info
+      info[:termsOfService] = config.terms_of_service_url if config.terms_of_service_url
+      info
+    end
+
     def build_paths
       paths = {}
 
@@ -58,6 +66,7 @@ module Docit
 
     def build_operation(operation)
       result = {
+        operationId: operation._operation_id || generate_operation_id(operation),
         summary: operation._summary || operation.action.humanize,
         description: operation._description || "",
         tags: operation._tags,
@@ -183,5 +192,15 @@ module Docit
         hash[ex[:name].to_s] = entry
       end
     end
+
+    def generate_operation_id(operation)
+      # "Api::V1::UsersController" → "users" ; "index" → "listUsers"
+      resource = operation.controller
+                          .gsub(/.*::/, "") # strip namespace
+                          .gsub(/Controller$/, "") # strip suffix
+      action = operation.action
+
+      "#{action}_#{resource}".gsub("::", "_").downcase
+    end
   end
 end

data/lib/docit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Docit
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/generators/docit/install/install_generator.rb

@@ -102,7 +102,7 @@ module Docit
         say ""
         say "Next steps:"
         say "  1. Edit config/initializers/docit.rb to customize your API docs"
-        say "  2. Add swagger_doc blocks or create doc files under app/docs/"
+        say "  2. Add doc_for blocks or create doc files under app/docs/"
         say "  3. Visit /api-docs to see your Swagger UI"
         say ""
         say "You can set up docs later with:"
@@ -146,7 +146,7 @@ module Docit
 
       def update_gitignore
         gitignore = Rails.root.join(".gitignore")
-        if !(File.exist?(gitignore))
+        unless File.exist?(gitignore)
           say "Warning: .gitignore not found. Add .docit_ai.yml manually to avoid committing your API key.", :yellow
           return
         end
@@ -167,7 +167,7 @@ module Docit
           choice = ask(prompt).to_s.strip
           return choice if choices.include?(choice)
 
-          say "Invalid choice. Please enter #{choices.join(', ')}.", :red
+          say "Invalid choice. Please enter #{choices.join(", ")}.", :red
         end
       end
 

data/lib/tasks/docit.rake

@@ -3,7 +3,7 @@
 namespace :docit do
   desc "Generate documentation for undocumented API endpoints using AI"
   task :autodoc, [:controller] => :environment do |_t, args|
-    dry_run = ENV.fetch("DRY_RUN", "0") == "1" || ARGV.include?("--dry-run")
+    dry_run = ENV.fetch("DRY_RUN", "0") == "1"
     controller_filter = args[:controller]
 
     runner = Docit::Ai::AutodocRunner.new(

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docit
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - S13G
@@ -49,6 +49,7 @@ files:
 - lib/docit/ai/autodoc_runner.rb
 - lib/docit/ai/client.rb
 - lib/docit/ai/configuration.rb
+- lib/docit/ai/doc_block_validator.rb
 - lib/docit/ai/doc_writer.rb
 - lib/docit/ai/gap_detector.rb
 - lib/docit/ai/groq_client.rb
@@ -77,14 +78,14 @@ files:
 - lib/generators/docit/install/templates/initializer.rb
 - lib/tasks/docit.rake
 - sig/docit.rbs
-homepage: https://github.com/S13G/docit
+homepage: https://docitruby.dev
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/S13G/docit
+  homepage_uri: https://docitruby.dev
   source_code_uri: https://github.com/S13G/docit
-  changelog_uri: https://github.com/S13G/docit/blob/main/CHANGELOG.md
-  documentation_uri: https://rubydoc.info/gems/docit
+  changelog_uri: https://github.com/S13G/docit/blob/master/CHANGELOG.md
+  documentation_uri: https://docitruby.dev/docs
   bug_tracker_uri: https://github.com/S13G/docit/issues
   rubygems_mfa_required: 'true'
 rdoc_options: []