oas_grape 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7cee578b32b694847532fbf186e9edf2f0418381b912417faf8181c32732144a
+  data.tar.gz: 96c7a37f3914b4a6ba4200687d232e4f0397fb8708b6e072f308f59d55fc5764
+SHA512:
+  metadata.gz: 301223cc381bdbaefdd210602b1a499df8c110537404c3a42811c6d69cf544583eaaae2b8b6b7661fec2ac57149cd776391af4d4a2659813f5cf60edff3acc78
+  data.tar.gz: 2a0a1ae22838e8d9c0c6a2f52e31a7165ac8f588668a7ee1a2b214616f2667a2243c67e732ecf8927654d70abb5b908e32c2bb790542eb70db0818829f6e96ae

data/README.md

@@ -0,0 +1,37 @@
+![Gem Version](https://img.shields.io/gem/v/oas_grape?color=E9573F)
+![GitHub License](https://img.shields.io/github/license/a-chacon/oas_grape?color=blue)
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/a-chacon/oas_grape/.github%2Fworkflows%2Fruby.yml)
+![Gem Total Downloads](https://img.shields.io/gem/dt/oas_grape)
+![Static Badge](https://img.shields.io/badge/Ruby-%3E%3D3.1.0-%23E9573F)
+
+# 📃 Open API Specification For Grape
+
+**OasGrape** is a tool for generating **automatic interactive documentation for your Grape APIs**. It generates an **OAS 3.1** document and displays it using **[RapiDoc](https://rapidocweb.com)**.
+
+It relies on the [OasCore](https://github.com/a-chacon/oas_core).
+
+![Screenshot](https://a-chacon.com/oas_core/assets/grape_theme.png)
+
+## Documentation
+
+For details on how to install, configure, and use OasGrape, 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=a-chacon/oas_grape&type=Date)](https://www.star-history.com/#a-chacon/oas_grape&Date)

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/oas_grape/configuration.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module OasGrape
+  class Configuration < OasCore::Configuration
+    attr_accessor :rapidoc_theme, :source_oas_path
+    attr_reader :include_mode
+
+    def initialize
+      super(info: generate_info_object)
+
+      @include_mode = :all
+      @rapidoc_theme = :rails
+      @source_oas_path = nil
+    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
+      "OasGrape"
+    end
+
+    def summary
+      "OasGrape: Automatic Interactive API Documentation for Grape"
+    end
+
+    def description
+      <<~DESC
+        # Welcome to OasGrape
+
+        OasGrape automatically generates interactive documentation for your Grape APIs using the OpenAPI Specification 3.1 (OAS 3.1) and displays it with a sleek UI.
+
+        ## Getting Started
+
+        You've successfully mounted the OasGrape 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 OasGrape!
+
+        Any questions visit the [OasGrape GitHub Repository](https://github.com/a-chacon/oas_grape).
+      DESC
+    end
+  end
+end

data/lib/oas_grape/oas_route_builder.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module OasGrape
+  class OasRouteBuilder
+    def self.build_from_grape_route(grape_route)
+      new(grape_route).build
+    end
+
+    def initialize(grape_route)
+      @grape_route = grape_route
+    end
+
+    def build
+      OasCore::OasRoute.new(
+        controller: controller,
+        method_name: method_name,
+        verb: verb,
+        path: path,
+        docstring: docstring,
+        source_string: source_string,
+        tags: tags
+      )
+    end
+
+    private
+
+    def controller
+      @grape_route.options[:namespace] || "unknown"
+    end
+
+    def method_name
+      @grape_route.options[:description] || "unknown"
+    end
+
+    def verb
+      @grape_route.request_method.downcase
+    end
+
+    def path
+      @grape_route.pattern.origin
+    end
+
+    def source_string
+      "Source not available" # Not applicable in this context
+    end
+
+    def docstring
+      detail = @grape_route.options.dig(:settings, :description, :detail) || @grape_route.options[:detail]
+      return "Docstring not available" unless detail
+
+      processed_lines = detail.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 StandardError
+      "Docstring not available"
+    end
+
+    def tags
+      detail = @grape_route.options[:detail] || ""
+
+      detail += "\n# @summary #{@grape_route.options[:description]}" if detail.empty? || !detail.include?("@summary")
+
+      parse_tags(detail)
+    end
+
+    def parse_tags(comment)
+      lines = comment.lines.map { |line| line.sub(/^# /, "") }
+      ::YARD::Docstring.parser.parse(lines.join).tags
+    end
+  end
+end

data/lib/oas_grape/route_extractor.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module OasGrape
+  class RouteExtractor
+    class << self
+      def host_routes
+        @host_routes ||= extract_grape_routes
+      end
+
+      def clear_cache
+        @host_routes = nil
+      end
+
+      private
+
+      def extract_grape_routes
+        grape_klasses = ObjectSpace.each_object(Class).select { |klass| klass < Grape::API }
+        routes = grape_klasses.flat_map(&:routes).uniq { |r| r.path + r.request_method.to_s }
+
+        routes = routes.map { |route| OasRouteBuilder.build_from_grape_route(route) }
+        filter_routes(routes)
+      end
+
+      def filter_routes(routes)
+        case OasGrape.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_grape/version.rb

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