oas_hanami 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a54ec2dcc566a43373e6345ad0dc9d5f6ce21decbb6ac136fadf3327241bf59e
+  data.tar.gz: ecec0f8eb9cc753bb89d6f9e47c05e90960a1273c983a2cec114057530f4cd0d
+SHA512:
+  metadata.gz: e16468c06d74fba996631455a353d9ada8da46b61b17aa0892ad6d58ce7a8b32f635020fd11dde6090c05cc726cec2269c2e4d4f41cf130746fe16dcf67a4f48
+  data.tar.gz: f7846391ca5a5cb186083ee9cc62eb57556fd00c36287047aff424160aff588a5e963b5a2c62b5d8549b9494bdb0ab1b102d6ae257d689e03cbb32080b936996

data/.release-please-config.json

@@ -0,0 +1,64 @@
+{
+  "release-type": "ruby",
+  "changelog-sections": [
+    {
+      "type": "feat",
+      "section": "Features"
+    },
+    {
+      "type": "feature",
+      "section": "Features"
+    },
+    {
+      "type": "fix",
+      "section": "Bug Fixes"
+    },
+    {
+      "type": "perf",
+      "section": "Performance Improvements"
+    },
+    {
+      "type": "revert",
+      "section": "Reverts"
+    },
+    {
+      "type": "docs",
+      "section": "Documentation"
+    },
+    {
+      "type": "style",
+      "section": "Styles",
+      "hidden": true
+    },
+    {
+      "type": "chore",
+      "section": "Miscellaneous Chores",
+      "hidden": true
+    },
+    {
+      "type": "refactor",
+      "section": "Code Refactoring"
+    },
+    {
+      "type": "test",
+      "section": "Tests"
+    },
+    {
+      "type": "build",
+      "section": "Build System",
+      "hidden": true
+    },
+    {
+      "type": "ci",
+      "section": "Continuous Integration",
+      "hidden": true
+    }
+  ],
+  "packages": {
+    ".": {
+      "release-type": "ruby",
+      "package-name": "oas_hanami",
+      "version-file": "lib/oas_hanami/version.rb"
+    }
+  }
+}

data/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.1.0"
+}

data/.rspec

@@ -0,0 +1,4 @@
+--format documentation
+--color
+--require spec_helper
+

data/.rspec_status

@@ -0,0 +1,11 @@
+example_id                                                           | status | run_time        |
+-------------------------------------------------------------------- | ------ | --------------- |
+./spec/bookshelf/spec/requests/books/create_spec.rb[1:1:1]           | failed | 0.00294 seconds |
+./spec/bookshelf/spec/requests/books/create_spec.rb[1:2:1]           | failed | 0.00016 seconds |
+./spec/bookshelf/spec/requests/books/index/pagination_spec.rb[1:1:1] | failed | 0.00012 seconds |
+./spec/bookshelf/spec/requests/books/index/pagination_spec.rb[1:2:1] | failed | 0.00008 seconds |
+./spec/bookshelf/spec/requests/books/index_spec.rb[1:1]              | failed | 0.00008 seconds |
+./spec/bookshelf/spec/requests/books/show_spec.rb[1:1:1]             | failed | 0.00008 seconds |
+./spec/bookshelf/spec/requests/books/show_spec.rb[1:2:1]             | failed | 0.00007 seconds |
+./spec/bookshelf/spec/requests/root_spec.rb[1:1]                     | failed | 0.00008 seconds |
+./spec/oas_hanami_spec.rb[1:1]                                       | passed | 0.00408 seconds |

data/.rubocop.yml

@@ -0,0 +1,15 @@
+inherit_from: .rubocop_todo.yml
+
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: disable
+  SuggestExtensions: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Style/Documentation:
+  Enabled: false

data/.rubocop_todo.yml

@@ -0,0 +1,20 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2025-06-15 19:33:58 UTC using RuboCop version 1.76.1.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 2
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
+# AllowedMethods: refine
+Metrics/BlockLength:
+  Max: 31
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
+# URISchemes: http, https
+Layout/LineLength:
+  Max: 235

data/.ruby-version

@@ -0,0 +1 @@
+3.4.4

data/.ruby.version

@@ -0,0 +1 @@
+3.4.4

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.1.0](https://github.com/a-chacon/oas_hanami/compare/oas_hanami-v0.0.1...oas_hanami/v0.1.0) (2025-06-15)
+
+
+### Features
+
+* initial release ([a622d09](https://github.com/a-chacon/oas_hanami/commit/a622d09d96243406eac3887e38c145fb0e962ac2))

data/README.md

@@ -0,0 +1,38 @@
+![Gem Version](https://img.shields.io/gem/v/oas_hanami?color=E9573F)
+![GitHub License](https://img.shields.io/github/license/a-chacon/oas_hanami?color=blue)
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/a-chacon/oas_hanami/.github%2Fworkflows%2Fruby.yml)
+![Gem Total Downloads](https://img.shields.io/gem/dt/oas_hanami)
+![Static Badge](https://img.shields.io/badge/Hanami-%3E%3D2.0.0-%23E9573F)
+![Static Badge](https://img.shields.io/badge/Ruby-%3E%3D3.1.0-%23E9573F)
+
+# 📃Open API Specification For Hanami
+
+OasHanami is a tool for generating **automatic interactive documentation for your Hanami APIs**. It generates an **OAS 3.1** document and displays it using **[RapiDoc](https://rapidocweb.com)**.
+
+Built for the modern [Hanami](https://hanamirb.org) framework, OasHanami leverages Hanami's lightweight and modular design, making it ideal for building scalable Ruby applications. It relies on the [OasCore](https://github.com/a-chacon/oas_core) gem for seamless OpenAPI integration.
+
+![Screenshot](https://a-chacon.com/assets/images/oas_hanami_ui.png)
+
+## Documentation
+
+For details on how to install, configure, and use OasHanami, please refer to the [OasCore MDBook](http://a-chacon.com/oas_core).
+
+## Contributing
+
+Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**. If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star⭐! Thanks again!
+
+If you plan a big feature, first open an issue to discuss it before any development.
+
+1. Fork the Project
+2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the Branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [GPL-3.0](https://www.gnu.org/licenses/gpl-3.0.en.html#license-text).
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=[USERNAME]/oas_hanami&type=Date)](https://www.star-history.com/#[USERNAME]/oas_hanami&Date)

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/oas_hanami/configuration.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module OasHanami
+  class Configuration < OasCore::Configuration
+    attr_accessor :rapidoc_theme
+    attr_reader :include_mode
+
+    def initialize
+      super(info: generate_info_object)
+
+      @include_mode = :all
+      @rapidoc_theme = :hanami
+    end
+
+    def include_mode=(value)
+      valid_modes = %i[all with_tags explicit]
+      raise ArgumentError, "include_mode must be one of #{valid_modes}" unless valid_modes.include?(value)
+
+      @include_mode = value
+    end
+
+    def generate_info_object
+      OasCore::Spec::Info.new(
+        title: title,
+        summary: summary,
+        description: description
+      )
+    end
+
+    def title
+      "OasHanami"
+    end
+
+    def summary
+      "OasHanami: Automatic Interactive API Documentation for Hanami"
+    end
+
+    def description
+      <<~DESC
+        # Welcome to OasHanami
+
+        OasHanami automatically generates interactive documentation for your Hanami APIs using the OpenAPI Specification 3.1 (OAS 3.1) and displays it with a sleek UI.
+
+        ## Getting Started
+
+        You've successfully mounted the OasHanami engine. This default documentation is based on your routes and automatically gathered information.
+
+        For more details, visit the official documentation: [OasCore Documentation](https://a-chacon.com/oas_core).
+
+        ## Features
+
+        - **Automatic OAS 3.1 Document Generation**: No manual specification required.
+        - **[RapiDoc](https://github.com/rapi-doc/RapiDoc) Integration**: Interactive API exploration.
+        - **Minimal Setup**: Basic documentation works out of the box.
+        - **Extensible**: Customize through configuration and YARD tags.
+
+        Explore your API documentation and enjoy the power of OasHanami!
+
+        Any questions visit the [OasHanami GitHub Repository](https://github.com/a-chacon/oas_hanami).
+      DESC
+    end
+  end
+end

data/lib/oas_hanami/hanami_route_formatter.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module OasHanami
+  class HanamiRouteFormatter
+    def call(routes, **_csv_opts)
+      routes
+    end
+  end
+end

data/lib/oas_hanami/inspector.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "hanami/router/inspector"
+
+module OasHanami
+  class Inspector < Hanami::Router::Inspector
+    def initialize(routes: [], formatter: HanamiRouteFormatter.new)
+      super(routes:, formatter:)
+    end
+  end
+end

data/lib/oas_hanami/oas_route_builder.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module OasHanami
+  class OasRouteBuilder
+    def self.build_from_hanami_route(hanami_route)
+      new(hanami_route).build
+    end
+
+    def initialize(hanami_route)
+      @hanami_route = hanami_route
+    end
+
+    def build
+      OasCore::OasRoute.new(
+        controller: controller,
+        method_name: method,
+        verb: verb,
+        path: path,
+        docstring: docstring,
+        source_string: source_string,
+        tags: tags
+      )
+    end
+
+    private
+
+    def controller_class
+      if @hanami_route.to.is_a?(String)
+        namespace = Hanami.app.name.gsub("App", "Actions")
+        parts = @hanami_route.to.split(".")
+        full_class_name = "#{namespace}::#{parts.map(&:camelize).join("::")}"
+
+        full_class_name.split("::").reduce(Object) { |mod, name| mod.const_get(name) }
+      else
+        @hanami_route.to
+      end
+    end
+
+    def controller
+      controller_class.to_s
+    end
+
+    def method
+      "handle"
+    end
+
+    def verb
+      @hanami_route.http_method.downcase
+    end
+
+    def path
+      @hanami_route.path
+    end
+
+    def source_string
+      controller_class.instance_method(method).source
+    rescue NameError
+      "Source not available"
+    end
+
+    def docstring
+      comment_lines = controller_class.instance_method(method).comment.lines
+      processed_lines = comment_lines.map { |line| line.sub(/^# /, "") }
+
+      filtered_lines = processed_lines.reject do |line|
+        line.include?("rubocop") ||
+          line.include?("TODO")
+      end
+
+      ::YARD::Docstring.parser.parse(filtered_lines.join).to_docstring
+    rescue NameError
+      "Docstring not available"
+    end
+
+    def tags
+      method_comment = controller_class.instance_method(method).comment
+
+      parse_tags(method_comment)
+    rescue NameError
+      []
+    end
+
+    def parse_tags(comment)
+      return [] unless comment
+
+      lines = comment.lines.map { |line| line.sub(/^# /, "") }
+      ::YARD::Docstring.parser.parse(lines.join).tags
+    end
+  end
+end

data/lib/oas_hanami/route_extractor.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module OasHanami
+  class RouteExtractor
+    class << self
+      def host_routes
+        @host_routes ||= extract_host_routes
+      end
+
+      def clear_cache
+        @host_routes = nil
+      end
+
+      def clean_route(route)
+        route.gsub("(.:format)", "").gsub(/:\w+/) { |match| "{#{match[1..]}}" }
+      end
+
+      private
+
+      def extract_host_routes
+        routes = Hanami.app.router.inspector.call
+        routes = transform_routes(routes)
+        filter_routes(routes)
+      end
+
+      def transform_routes(routes)
+        routes.map do |r|
+          next unless r.to.is_a? String
+
+          OasRouteBuilder.build_from_hanami_route(r)
+        end.compact
+      end
+
+      def filter_routes(routes)
+        case OasHanami.config.include_mode
+        when :with_tags
+          routes.select { |route| route.tags.any? }
+        when :explicit
+          routes.select { |route| route.tags.any? { |t| t.tag_name == "oas_include" } }
+        else
+          routes
+        end
+      end
+    end
+  end
+end

data/lib/oas_hanami/version.rb

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