RubyGems - docit - Versions diffs - 0.1.0 - Mend

docit 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (31) hide show

checksums.yaml +7 -0
data/.github/ISSUE_TEMPLATE/bug_report.md +31 -0
data/.github/ISSUE_TEMPLATE/feature_request.md +27 -0
data/.github/PULL_REQUEST_TEMPLATE.md +15 -0
data/.github/workflows/ci.yml +30 -0
data/CHANGELOG.md +15 -0
data/CODE_OF_CONDUCT.md +39 -0
data/CONTRIBUTING.md +78 -0
data/LICENSE.txt +21 -0
data/README.md +416 -0
data/Rakefile +12 -0
data/app/controllers/docit/ui_controller.rb +56 -0
data/config/routes.rb +6 -0
data/lib/docit/builders/parameter_builder.rb +28 -0
data/lib/docit/builders/request_body_builder.rb +45 -0
data/lib/docit/builders/response_builder.rb +47 -0
data/lib/docit/configuration.rb +66 -0
data/lib/docit/doc_file.rb +56 -0
data/lib/docit/dsl.rb +28 -0
data/lib/docit/engine.rb +19 -0
data/lib/docit/operation.rb +58 -0
data/lib/docit/registry.rb +26 -0
data/lib/docit/route_inspector.rb +60 -0
data/lib/docit/schema_definition.rb +33 -0
data/lib/docit/schema_generator.rb +187 -0
data/lib/docit/version.rb +5 -0
data/lib/docit.rb +48 -0
data/lib/generators/docit/install/install_generator.rb +29 -0
data/lib/generators/docit/install/templates/initializer.rb +18 -0
data/sig/docit.rbs +4 -0
metadata +90 -0

data/app/controllers/docit/ui_controller.rb ADDED Viewed

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+module Docit
+  class UiController < ActionController::Base
+    def index
+      render html: swagger_ui_html.html_safe, layout: false
+    end
+    def spec
+      RouteInspector.eager_load_controllers!
+      render json: SchemaGenerator.generate
+    end
+    private
+    def swagger_ui_html
+      spec_url = "#{request.base_url}#{Docit::Engine.routes.url_helpers.spec_path}"
+      escaped_title = ERB::Util.html_escape(Docit.configuration.title)
+      <<~HTML
+        <!DOCTYPE html>
+        <html lang="en">
+        <head>
+          <meta charset="UTF-8">
+          <meta name="viewport" content="width=device-width, initial-scale=1.0">
+          <title>#{escaped_title}</title>
+          <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css" />
+          <style>
+            html { box-sizing: border-box; overflow-y: scroll; }
+            *, *:before, *:after { box-sizing: inherit; }
+            body { margin: 0; background: #fafafa; }
+          </style>
+        </head>
+        <body>
+          <div id="swagger-ui"></div>
+          <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+          <script>
+            SwaggerUIBundle({
+              url: "#{spec_url}",
+              dom_id: '#swagger-ui',
+              presets: [
+                SwaggerUIBundle.presets.apis,
+                SwaggerUIBundle.SwaggerUIStandalonePreset
+              ],
+              layout: "BaseLayout",
+              deepLinking: true,
+              showExtensions: true,
+              showCommonExtensions: true
+            })
+          </script>
+        </body>
+        </html>
+      HTML
+    end
+  end
+end

data/config/routes.rb ADDED Viewed

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+Docit::Engine.routes.draw do
+  root to: "ui#index"
+  get "spec", to: "ui#spec", defaults: { format: :json }
+end

data/lib/docit/builders/parameter_builder.rb ADDED Viewed

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+module Docit
+  module Builders
+    # Collects query, path, and header parameters for an operation.
+    class ParameterBuilder
+      attr_reader :params
+      def initialize
+        @params = []
+      end
+      def add(name, location:, type: :string, required: false, description: nil, example: nil, enum: nil, **opts)
+        param = {
+          name: name.to_s,
+          in: location.to_s,
+          required: required,
+          schema: { type: type.to_s }
+        }
+        param[:description] = description if description
+        param[:schema][:enum] = enum if enum
+        param[:schema][:example] = example if example
+        param[:schema].merge!(opts)
+        @params << param
+      end
+    end
+  end
+end

data/lib/docit/builders/request_body_builder.rb ADDED Viewed

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+module Docit
+  module Builders
+    # Builds the schema for a request body, including properties,
+    # required fields, and schema references.
+    class RequestBodyBuilder
+      attr_reader :properties, :required, :content_type, :schema_ref
+      def initialize(required: false, content_type: "application/json")
+        @required = required
+        @content_type = content_type
+        @properties = []
+        @schema_ref = nil
+      end
+      def schema(ref:)
+        @schema_ref = ref.to_sym
+      end
+      def property(name, type:, required: false, format: nil, example: nil, enum: nil, description: nil, items: nil,
+                   **opts, &block)
+        prop = { name: name, type: type, required: required }
+        prop[:format] = format if format
+        prop[:example] = example if example
+        prop[:enum] = enum if enum
+        prop[:description] = description if description
+        prop[:items] = items if items
+        prop.merge!(opts)
+        if block_given?
+          nested = self.class.new(required: @required, content_type: @content_type)
+          nested.instance_eval(&block)
+          prop[:children] = nested.properties
+        end
+        @properties << prop
+      end
+      def required_properties
+        @properties.select { |prop| prop[:required] }.map { |prop| prop[:name].to_s }
+      end
+    end
+  end
+end

data/lib/docit/builders/response_builder.rb ADDED Viewed

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+module Docit
+  module Builders
+    # Builds the schema for a single HTTP response, including properties,
+    # examples, and schema references.
+    class ResponseBuilder
+      attr_reader :status, :description, :properties, :examples, :schema_ref
+      def initialize(status:, description:)
+        @status = status
+        @description = description
+        @properties = []
+        @examples = []
+        @schema_ref = nil
+      end
+      def schema(ref:)
+        @schema_ref = ref.to_sym
+      end
+      def property(name, type:, format: nil, example: nil, enum: nil, description: nil, items: nil, **opts, &block)
+        prop = { name: name, type: type }
+        prop[:format] = format if format
+        prop[:example] = example if example
+        prop[:enum] = enum if enum
+        prop[:description] = description if description
+        prop[:items] = items if items
+        prop.merge!(opts)
+        if block_given?
+          nested = self.class.new(status: @status, description: @description)
+          nested.instance_eval(&block)
+          prop[:children] = nested.properties
+        end
+        @properties << prop
+      end
+      def example(name, value, description: nil)
+        ex = { name: name, value: value }
+        ex[:description] = description if description
+        @examples << ex
+      end
+    end
+  end
+end

data/lib/docit/configuration.rb ADDED Viewed

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+module Docit
+  # Holds global API documentation settings: metadata, authentication, tags, and servers.
+  class Configuration
+    attr_accessor :title, :version, :description, :base_url
+    def initialize
+      @title = "API Documentation"
+      @version = "1.0.0"
+      @description = ""
+      @base_url = "/"
+      @security_schemes = {}
+      @tags = []
+      @servers = []
+    end
+    def auth(type, **options)
+      case type.to_s.downcase
+      when "basic"
+        @security_schemes[:basic_auth] = {
+          type: "http",
+          scheme: "basic"
+        }
+      when "bearer"
+        @security_schemes[:bearer_auth] = {
+          type: "http",
+          scheme: "bearer",
+          bearerFormat: options[:bearer_format] || "JWT"
+        }
+      when "api_key"
+        @security_schemes[:api_key] = {
+          type: "apiKey",
+          name: options[:name] || "X-API-Key",
+          in: options[:location] || "header"
+        }
+      else
+        raise ArgumentError, "Unsupported auth type: #{type}"
+      end
+    end
+    def security_schemes
+      @security_schemes.dup
+    end
+    def tag(name, description: nil)
+      entry = { name: name.to_s }
+      entry[:description] = description if description
+      @tags << entry
+    end
+    def tags
+      @tags.dup
+    end
+    def server(url, description: nil)
+      entry = { url: url.to_s }
+      entry[:description] = description if description
+      @servers << entry
+    end
+    def servers
+      @servers.dup
+    end
+  end
+end

data/lib/docit/doc_file.rb ADDED Viewed

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+module Docit
+  # DocFile lets you define API documentation in separate files,
+  # keeping your controllers clean. Extend any module with DocFile,
+  # then use `doc :action_name do ... end` to define docs.
+  #
+  # Usage:
+  #
+  #   # app/docs/users_docs.rb
+  #   module UsersDocs
+  #     extend Docit::DocFile
+  #
+  #     doc :index do
+  #       summary "List users"
+  #       tags "Users"
+  #       response 200, "Users retrieved"
+  #     end
+  #
+  #     doc :create do
+  #       summary "Create a user"
+  #       tags "Users"
+  #       request_body required: true do
+  #         property :email, type: :string, required: true
+  #       end
+  #       response 201, "User created"
+  #     end
+  #   end
+  #
+  #   # app/controllers/users_controller.rb
+  #   class UsersController < ApplicationController
+  #     use_docs UsersDocs
+  #
+  #     def index; end
+  #     def create; end
+  #   end
+  #
+  module DocFile
+    def self.extended(base)
+      base.instance_variable_set(:@_docs, {})
+    end
+    # The block receives the same DSL as swagger_doc.
+    def doc(action, &block)
+      @_docs[action.to_sym] = block
+    end
+    def [](action)
+      @_docs[action.to_sym]
+    end
+    def actions
+      @_docs.keys
+    end
+  end
+end

data/lib/docit/dsl.rb ADDED Viewed

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+module Docit
+  # Included in all Rails controllers via the Engine.
+  # Provides +swagger_doc+ and +use_docs+ class methods.
+  module DSL
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+    module ClassMethods
+      def swagger_doc(action, &block)
+        operation = Operation.new(
+          controller: name,
+          action: action
+        )
+        operation.instance_eval(&block) if block_given?
+        Registry.register(operation)
+      end
+      def use_docs(doc_module)
+        doc_module.actions.each do |action|
+          swagger_doc(action, &doc_module[action])
+        end
+      end
+    end
+  end
+end

data/lib/docit/engine.rb ADDED Viewed

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+require "docit"
+module Docit
+  class Engine < ::Rails::Engine
+    isolate_namespace Docit
+    initializer "docit.include_dsl" do
+      ActiveSupport.on_load(:action_controller_api) do
+        include Docit::DSL
+      end
+      ActiveSupport.on_load(:action_controller_base) do
+        include Docit::DSL
+      end
+    end
+  end
+end

data/lib/docit/operation.rb ADDED Viewed

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+module Docit
+  # Represents the documentation for a single controller action.
+  # Created by +swagger_doc+ and stored in the {Registry}.
+  class Operation
+    attr_reader :controller, :action, :_summary, :_description,
+                :_tags, :_responses, :_request_body, :_parameters,
+                :_security, :_deprecated
+    def initialize(controller:, action:)
+      @controller = controller
+      @action = action.to_s
+      @_tags = []
+      @_responses = []
+      @_parameters = Builders::ParameterBuilder.new
+      @_request_body = nil
+      @_security = []
+      @_deprecated = false
+    end
+    def summary(text)
+      @_summary = text
+    end
+    def description(text)
+      @_description = text
+    end
+    def tags(*tags_list)
+      @_tags = tags_list.flatten
+    end
+    def deprecated(value: true)
+      @_deprecated = value
+    end
+    def security(scheme)
+      @_security << scheme
+    end
+    def parameter(name, location:, type: :string, required: false, description: nil, **opts)
+      @_parameters.add(name, location: location, type: type, required: required, description: description, **opts)
+    end
+    def request_body(required: false, content_type: "application/json", &block)
+      builder = Builders::RequestBodyBuilder.new(required: required, content_type: content_type)
+      builder.instance_eval(&block) if block_given?
+      @_request_body = builder
+    end
+    def response(status, description = "", &block)
+      builder = Builders::ResponseBuilder.new(status: status, description: description)
+      builder.instance_eval(&block) if block_given?
+      @_responses << builder
+    end
+  end
+end

data/lib/docit/registry.rb ADDED Viewed

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+module Docit
+  # Central store for all documented operations.
+  class Registry
+    class << self
+      def operations
+        @operations ||= []
+      end
+      def register(operation)
+        operations << operation
+      end
+      def find(controller:, action:)
+        operations.find do |op|
+          op.controller == controller && op.action == action
+        end
+      end
+      def clear!
+        @operations = []
+      end
+    end
+  end
+end

data/lib/docit/route_inspector.rb ADDED Viewed

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+module Docit
+  # Introspects Rails routes to map controller actions to HTTP paths and methods.
+  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.
+    def self.eager_load_controllers!
+      return if defined?(Rails).nil? || Rails.application.routes.nil?
+      controller_paths = Rails.application.routes.routes.filter_map do |route|
+        route.defaults[:controller]
+      end.uniq
+      controller_paths.each do |path|
+        class_name = "#{path}_controller".camelize
+        class_name.constantize
+      rescue NameError
+        # Skip controllers that can't be loaded (e.g., Rails internal routes)
+      end
+    end
+    def self.routes_for(controller_name, action_name)
+      return [] if defined?(Rails).nil? || Rails.application.routes.nil?
+      action = action_name.to_s
+      # Convert Api::V1::AuthController to api/v1/auth
+      controller_path = controller_name.underscore.delete_suffix("_controller").gsub("::", "/")
+      Rails.application.routes.routes.filter_map do |route|
+        next if route.defaults[:controller] != controller_path
+        next if route.defaults[:action] != action
+        verb = extract_verb(route)
+        next if VALID_METHODS.exclude?(verb)
+        { path: normalize_path(route.path.spec.to_s), method: verb }
+      end
+    end
+    def self.extract_verb(route)
+      verb = route.verb
+      verb = verb.source if verb.is_a?(Regexp)
+      verb.to_s.downcase.gsub(/[^a-z]/, "")
+    end
+    private_class_method :extract_verb
+    def self.normalize_path(path)
+      path
+        .gsub("(.:format)", "")
+        .gsub(/\(\.?:(\w+)\)/, '{\1}')
+        .gsub(/:(\w+)/, '{\1}')
+    end
+    private_class_method :normalize_path
+  end
+end

data/lib/docit/schema_definition.rb ADDED Viewed

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+module Docit
+  # A reusable schema definition that can be referenced via +$ref+.
+  # Defined with {Docit.define_schema} and rendered under
+  # +components/schemas+ in the OpenAPI spec.
+  class SchemaDefinition
+    attr_reader :name, :properties
+    def initialize(name)
+      @name = name
+      @properties = []
+    end
+    def property(prop_name, type:, format: nil, example: nil, enum: nil, description: nil, items: nil, **opts, &block)
+      prop = { name: prop_name, type: type }
+      prop[:format] = format if format
+      prop[:example] = example if example
+      prop[:enum] = enum if enum
+      prop[:description] = description if description
+      prop[:items] = items if items
+      prop.merge!(opts)
+      if block_given?
+        nested = self.class.new(:"#{@name}_#{prop_name}")
+        nested.instance_eval(&block)
+        prop[:children] = nested.properties
+      end
+      @properties << prop
+    end
+  end
+end