docit 0.1.0

data/lib/docit/schema_generator.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module Docit
+  # Converts the Registry of operations and Configuration into an OpenAPI 3.0.3 spec hash.
+  class SchemaGenerator
+    def self.generate
+      new.generate
+    end
+
+    def generate
+      config = Docit.configuration
+
+      spec = {
+        openapi: "3.0.3",
+        info: {
+          title: config.title,
+          version: config.version,
+          description: config.description
+        },
+        paths: build_paths,
+        components: {
+          securitySchemes: config.security_schemes
+        }
+      }
+
+      tag_defs = config.tags
+      spec[:tags] = tag_defs if tag_defs.any?
+
+      server_defs = config.servers
+      spec[:servers] = server_defs if server_defs.any?
+
+      schemas = build_component_schemas
+      spec[:components][:schemas] = schemas if schemas.any?
+
+      spec
+    end
+
+    private
+
+    def build_paths
+      paths = {}
+
+      Docit::Registry.operations.each do |operation|
+        routes = RouteInspector.routes_for(operation.controller, operation.action)
+        next if routes.empty?
+
+        routes.each do |route|
+          path = route[:path]
+          method = route[:method]
+
+          paths[path] ||= {}
+          paths[path][method] = build_operation(operation)
+        end
+      end
+
+      paths
+    end
+
+    def build_operation(operation)
+      result = {
+        summary: operation._summary || operation.action.humanize,
+        description: operation._description || "",
+        tags: operation._tags,
+        responses: build_responses(operation._responses)
+      }
+
+      params = operation._parameters.params
+      result[:parameters] = params if params.any?
+
+      result[:requestBody] = build_request_body(operation._request_body) if operation._request_body
+      result[:deprecated] = true if operation._deprecated
+      result[:security] = operation._security.map { |s| { s.to_s => [] } } if operation._security.any?
+
+      result
+    end
+
+    def build_responses(response_builders)
+      return { "200" => { description: "Success" } } if response_builders.empty?
+
+      response_builders.each_with_object({}) do |builder, hash|
+        entry = { description: builder.description }
+
+        if builder.schema_ref
+          schema = { "$ref" => "#/components/schemas/#{builder.schema_ref}" }
+          content = { "application/json" => { schema: schema } }
+          content["application/json"][:examples] = build_examples(builder.examples) if builder.examples.any?
+          entry[:content] = content
+        elsif builder.properties.any?
+          schema = {
+            type: "object",
+            properties: build_properties(builder.properties)
+          }
+          content = { "application/json" => { schema: schema } }
+          content["application/json"][:examples] = build_examples(builder.examples) if builder.examples.any?
+          entry[:content] = content
+        end
+
+        hash[builder.status.to_s] = entry
+      end
+    end
+
+    def build_request_body(request_body_builder)
+      if request_body_builder.schema_ref
+        schema = { "$ref" => "#/components/schemas/#{request_body_builder.schema_ref}" }
+      else
+        schema = {
+          type: "object",
+          properties: build_properties(request_body_builder.properties)
+        }
+
+        required_properties = request_body_builder.required_properties
+        schema[:required] = required_properties if required_properties.any?
+      end
+
+      {
+        required: request_body_builder.required,
+        content: {
+          request_body_builder.content_type => { schema: schema }
+        }
+      }
+    end
+
+    def build_properties(props)
+      props.each_with_object({}) do |prop, hash|
+        schema = build_property_schema(prop)
+        hash[prop[:name].to_s] = schema
+      end
+    end
+
+    def build_property_schema(prop)
+      type = prop[:type].to_s
+
+      if type == "file"
+        schema = { type: "string", format: "binary" }
+        schema[:description] = prop[:description] if prop[:description]
+        schema
+      elsif type == "array"
+        schema = { type: "array" }
+        if prop[:children]
+          schema[:items] = {
+            type: "object",
+            properties: build_properties(prop[:children])
+          }
+        else
+          items_type = prop[:items]&.to_s || "string"
+          schema[:items] = { type: items_type }
+        end
+        schema[:description] = prop[:description] if prop[:description]
+        schema[:example] = prop[:example] if prop[:example]
+        schema
+      elsif type == "object" && prop[:children]
+        schema = {
+          type: "object",
+          properties: build_properties(prop[:children])
+        }
+        schema[:description] = prop[:description] if prop[:description]
+        schema[:example] = prop[:example] if prop[:example]
+        schema
+      else
+        schema = { type: type }
+        schema[:format] = prop[:format].to_s if prop[:format]
+        schema[:enum] = prop[:enum] if prop[:enum]
+        schema[:example] = prop[:example] if prop[:example]
+        schema[:description] = prop[:description] if prop[:description]
+        schema
+      end
+    end
+
+    def build_component_schemas
+      Docit.schemas.each_with_object({}) do |(name, definition), hash|
+        schema = {
+          type: "object",
+          properties: build_properties(definition.properties)
+        }
+        hash[name.to_s] = schema
+      end
+    end
+
+    def build_examples(examples)
+      examples.each_with_object({}) do |ex, hash|
+        entry = { value: ex[:value] }
+        entry[:description] = ex[:description] if ex[:description]
+        hash[ex[:name].to_s] = entry
+      end
+    end
+  end
+end

data/lib/docit/version.rb

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

data/lib/docit.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "docit/version"
+require_relative "docit/configuration"
+require_relative "docit/registry"
+require_relative "docit/builders/request_body_builder"
+require_relative "docit/builders/response_builder"
+require_relative "docit/builders/parameter_builder"
+require_relative "docit/operation"
+require_relative "docit/schema_definition"
+require_relative "docit/doc_file"
+require_relative "docit/route_inspector"
+require_relative "docit/schema_generator"
+require_relative "docit/dsl"
+
+# Docit is a decorator-style API documentation gem for Ruby on Rails.
+# It generates OpenAPI 3.0.3 specs from clean DSL macros on your controllers.
+module Docit
+  class Error < StandardError; end
+
+  class << self
+    def configure
+      yield configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    def schemas
+      @schemas ||= {}
+    end
+
+    def define_schema(name, &block)
+      definition = SchemaDefinition.new(name)
+      definition.instance_eval(&block) if block_given?
+      schemas[name.to_sym] = definition
+    end
+
+    def reset_schemas!
+      @schemas = {}
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Docit
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      desc "Creates a Docit initializer and mounts the engine in routes"
+      source_root File.expand_path("templates", __dir__)
+
+      def copy_initializer
+        template "initializer.rb", "config/initializers/docit.rb"
+      end
+
+      def mount_engine
+        route 'mount Docit::Engine => "/api-docs"'
+      end
+
+      def print_instructions
+        say ""
+        say "Docit installed successfully!", :green
+        say ""
+        say "Next steps:"
+        say "  1. Edit config/initializers/docit.rb to customize your API docs"
+        say "  2. Add swagger_doc blocks to your controller actions"
+        say "  3. Visit /api-docs to see your Swagger UI"
+        say ""
+      end
+    end
+  end
+end

data/lib/generators/docit/install/templates/initializer.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+Docit.configure do |config|
+  # The title shown in Swagger UI
+  config.title = "<%= Rails.application.class.module_parent_name rescue 'My API' %>"
+
+  # API version
+  config.version = "1.0.0"
+
+  # Description shown in Swagger UI
+  config.description = "API documentation powered by Docit"
+
+  # Authentication scheme (options: :bearer, :basic, :api_key)
+  # config.auth :bearer
+
+  # For API key auth:
+  # config.auth :api_key, name: "X-API-Key", location: "header"
+end

data/sig/docit.rbs

@@ -0,0 +1,4 @@
+module Docit
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification
+name: docit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- S13G
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: Docit lets you write OpenAPI 3.0 docs as clean DSL macros directly on
+  your Rails controller actions. No RSpec integration required, no external doc files.
+  Just annotate and go.
+email:
+- siegdomain1@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/ISSUE_TEMPLATE/bug_report.md"
+- ".github/ISSUE_TEMPLATE/feature_request.md"
+- ".github/PULL_REQUEST_TEMPLATE.md"
+- ".github/workflows/ci.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- app/controllers/docit/ui_controller.rb
+- config/routes.rb
+- lib/docit.rb
+- lib/docit/builders/parameter_builder.rb
+- lib/docit/builders/request_body_builder.rb
+- lib/docit/builders/response_builder.rb
+- lib/docit/configuration.rb
+- lib/docit/doc_file.rb
+- lib/docit/dsl.rb
+- lib/docit/engine.rb
+- lib/docit/operation.rb
+- lib/docit/registry.rb
+- lib/docit/route_inspector.rb
+- lib/docit/schema_definition.rb
+- lib/docit/schema_generator.rb
+- lib/docit/version.rb
+- lib/generators/docit/install/install_generator.rb
+- lib/generators/docit/install/templates/initializer.rb
+- sig/docit.rbs
+homepage: https://github.com/S13G/docket
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/S13G/docket
+  source_code_uri: https://github.com/S13G/docket
+  changelog_uri: https://github.com/S13G/docket/blob/main/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/docit
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Decorator-style Swagger/OpenAPI documentation generator for Ruby on Rails.
+test_files: []