oas_rails 0.7.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52858aae429b158f26e303387df144ff64845bb420e7abc329495c6c984a5f2a
-  data.tar.gz: 39ed4dbc661f79d9ecc289900004ae18a07726300762beabffca1714b2f9de8f
+  metadata.gz: 05b39d8ca4348b3da83595a029b436a73ba17a7a6da61ff61b09c02dd6147e7f
+  data.tar.gz: e8ef2175c8824dc45c63ef2aa112a1339ff5c4db779635ea4067d7bfd6dd75b8
 SHA512:
-  metadata.gz: 2666274a5c7fe0656adef0a5d56593885f4f85eccfe7a4c4708d29e2a86f7f79afb5d830a97e7ff6902cab8f554243b2302b4887b82efcbc3111150d784ee385
-  data.tar.gz: c12f2cde7a1f1ce6cf2ff950971e50de455f9938456ad423d2235916c121972b5c4dbe08a873dd0dd57ee2878f59d11a2a9dca0ee8301fd433582e03bcf0a844
+  metadata.gz: a1cce603fbc0064bc84a3a953026aae6eb914b33872b20ebb1620195a4e4105736965c3816e664a708b4367adacce57d7003fb23646908f0ad5337f6a34fa5ee
+  data.tar.gz: 070ec97c6bb4e46cfcd1f6f5b1d5a71fda212dd8d197c74623900ff057d614f2a387aa79c67eb7fd832bd7b36ae2fefd105b8159991263fd219b7a9718691e7a

data/README.md

@@ -5,10 +5,14 @@
 ![Static Badge](https://img.shields.io/badge/Rails-%3E%3D7.0.0-%23E9573F)
 ![Static Badge](https://img.shields.io/badge/Ruby-%3E%3D3.1.0-%23E9573F)
 
-# Open API Specification For Rails
+# 📃Open API Specification For Rails
 
 OasRails is a Rails engine for generating **automatic interactive documentation for your Rails APIs**. It generates an **OAS 3.1** document and displays it using **[RapiDoc](https://rapidocweb.com)**.
 
+🎬 A Demo Video Here:
+https://vimeo.com/1013687332
+🎬
+
 ![Screenshot](https://a-chacon.com/assets/images/oas_rails_ui.png)
 
 ## Related Projects
@@ -25,7 +29,7 @@ OasRails is a Rails engine for generating **automatic interactive documentation
 - **Simple**: Complement default documentation with a few comments; no need to learn a complex DSL
 - **Pure Ruby on Rails APIs**: No additional frameworks needed (e.g., Grape, RSpec)
 
-## Motivation
+## 📽️ Motivation
 
 After experiencing the interactive documentation in Python's fast-api framework, I sought similar functionality in Ruby on Rails. Unable to find a suitable solution, I [asked on Stack Overflow](https://stackoverflow.com/questions/71947018/is-there-a-way-to-generate-an-interactive-documentation-for-rails-apis) years ago. Now, with some free time while freelancing as an API developer, I decided to build my own tool.
 
@@ -33,7 +37,7 @@ After experiencing the interactive documentation in Python's fast-api framework,
 
 The goal is to minimize the effort required to create comprehensive documentation. By following REST principles in Rails, we believe this is achievable. You can enhance the documentation using [Yard](https://yardoc.org/) tags.
 
-## Table of Contents
+## 📋 Table of Contents
 
 - [Installation](#installation)
 - [Configuration](#configuration)
@@ -74,7 +78,7 @@ The goal is to minimize the effort required to create comprehensive documentatio
 
 You'll now have **basic documentation** based on your routes and automatically gathered information at `localhost:3000/docs`. To enhance it, create an initializer file and add [Yard](https://yardoc.org/) tags to your controller methods.
 
-## Configuration
+## ⚙️ Configuration
 
 To configure OasRails, you MUST create an initializer file including all your settings. The first step is to create your initializer file, which you can easily do with:
 
@@ -107,6 +111,7 @@ Then fill it with your data. Below are the available configuration options:
 - `config.autodiscover_request_body`: Automatically detects request bodies for create/update methods. Default is `true`.
 - `config.autodiscover_responses`: Automatically detects responses from controller renders. Default is `true`.
 - `config.api_path`: Sets the API path if your API is under a different namespace.
+- `config.ignored_actions`: Sets an array with the controller or controller#action. No necessary to add api_path before.
 
 ### Authentication Settings
 
@@ -122,7 +127,7 @@ Then fill it with your data. Below are the available configuration options:
 
 - `config.response_body_of_default`: body for use in default responses. It must be a String hash like the used in request body tags. Default: "{ message: String }"
 
-## Usage
+## 📓 Usage
 
 In addition to the information provided in the initializer file and the data that can be extracted from the routes and methods automatically, it is essential to document your API in the following way. The documentation is created **with the help of YARD**, so the methods are documented with **comment tags**.
 
@@ -147,11 +152,11 @@ Used to add a summary to the endpoint. It replaces the default summary/title of
 
 **Structure**: `@parameter name(position) [type] text`
 
-Represents a parameter for the endpoint. The position can be: `header`, `path`, `cookie`, or `query`. The type should be a valid Ruby class: `String`, `Integer`, `Array<String>`, etc. Add a `!` after the class to indicate a required parameter.
+Represents a parameter for the endpoint. The position can be: `header`, `path`, `cookie`, or `query`. The type should be a valid Ruby class: `String`, `Integer`, `Array<String>`, etc. Add a `!` before the class to indicate a required parameter.
 
 **Examples**:
 `# @parameter page(query) [Integer] The page number.`
-`# @parameter slug(path) [String!] Slug of the Project.`
+`# @parameter slug(path) [!String] Slug of the Project.`
 
 </details>
 
@@ -333,7 +338,7 @@ class UsersController < ApplicationController
 end
 ```
 
-## Securing the OasRails Engine
+## 🔒Securing the OasRails Engine
 
 To secure the OasRails engine, which exposes an endpoint for showing the OAS definition, you can configure authentication to ensure that only authorized users have access. Here are a few methods to achieve this:
 
@@ -382,7 +387,7 @@ ActiveSupport.on_load(:oas_rails_application_controller) do
 end
 ```
 
-## Customizing the View
+## ⛏️ Customizing the View
 
 The OasRails engine provides an easy way to display your OpenAPI Specification (OAS) within your Rails application. By default, it includes an `index` view in the `OasRailsController` that displays [RapiDoc](https://rapidocweb.com/) through a CDN with default configurations. You can easily override this view to replace RapiDoc entirely or configure it differently.
 

data/app/controllers/oas_rails/oas_rails_controller.rb

@@ -1,10 +1,11 @@
 module OasRails
   class OasRailsController < ApplicationController
-    layout false
+    # Include URL help if the layout is a user-customized layout.
+    include Rails.application.routes.url_helpers
 
     def index
       respond_to do |format|
-        format.html
+        format.html { render "index", layout: OasRails.config.layout }
         format.json do
           render json: OasRails.build.to_json, status: :ok
         end

data/app/views/layouts/oas_rails/application.html.erb

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title><%= OasRails.config.info.title %></title>
+    <%= csrf_meta_tags %>
+    <%= csp_meta_tag %>
+    <meta charset="utf-8">
+    <!-- Important: rapi-doc uses utf8 characters -->
+  </head>
+  <body>
+    <%= yield %>
+  </body>
+</html>

data/app/views/oas_rails/oas_rails/index.html.erb

@@ -1,27 +1,15 @@
-<!DOCTYPE html>
-<html>
-  <head>
-    <title><%= OasRails.config.info.title %></title>
-    <%= csrf_meta_tags %>
-    <%= csp_meta_tag %>
-    <meta charset="utf-8">
-    <!-- Important: rapi-doc uses utf8 characters -->
-    <script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script>
-  </head>
-  <body>
-    <rapi-doc
-      spec-url = "<%= OasRails::Engine.routes.find_script_name({}) %>.json"
-      theme = "dark"
-      bg-color="#0F172A"
-      text-color= "#f7f7f7"
-      show-header = 'false'
-      primary-color = "#2de410"
-      font-size="largest"
-      show-method-in-nav-bar="as-colored-text"
-      nav-text-color="#f7f7f7"
-      nav-item-spacing="relaxed"
-      allow-spec-file-download="true"
-      >
-    </rapi-doc>
-  </body>
-</html>
+<script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script>
+<rapi-doc
+  spec-url = "<%= OasRails::Engine.routes.find_script_name({}) %>.json"
+  theme = "dark"
+  bg-color="#0F172A"
+  text-color= "#f7f7f7"
+  show-header = 'false'
+  primary-color = "#2de410"
+  font-size="largest"
+  show-method-in-nav-bar="as-colored-text"
+  nav-text-color="#f7f7f7"
+  nav-item-spacing="relaxed"
+  allow-spec-file-download="true"
+  >
+</rapi-doc>

data/lib/generators/oas_rails/config/templates/oas_rails_initializer.rb

@@ -63,6 +63,15 @@ OasRails.configure do |config|
   # API path configuration if your API is under a different namespace
   # config.api_path = "/"
 
+  # Apply your custom layout. Should be the name of your layout file
+  # Example: "application" if file named application.html.erb
+  # Default: false
+  # config.layout = "application"
+
+  # Excluding custom controlers or controlers#action
+  # Example: ["projects", "users#new"]
+  # config.ignored_actions = []
+
   # #######################
   # Authentication Settings
   # #######################

data/lib/oas_rails/configuration.rb

@@ -1,10 +1,12 @@
 module OasRails
   class Configuration
     attr_accessor :info,
+                  :layout,
                   :default_tags_from,
                   :autodiscover_request_body,
                   :autodiscover_responses,
                   :api_path,
+                  :ignored_actions,
                   :security_schemas,
                   :authenticate_all_routes_by_default,
                   :set_default_responses,
@@ -14,6 +16,7 @@ module OasRails
 
     def initialize
       @info = Spec::Info.new
+      @layout = false
       @servers = default_servers
       @tags = []
       @swagger_version = '3.1.0'
@@ -21,6 +24,7 @@ module OasRails
       @autodiscover_request_body = true
       @autodiscover_responses = true
       @api_path = "/"
+      @ignored_actions = []
       @authenticate_all_routes_by_default = true
       @security_schema = nil
       @security_schemas = {}

data/lib/oas_rails/extractors/route_extractor.rb

@@ -93,6 +93,7 @@ module OasRails
           return false if RAILS_DEFAULT_CONTROLLERS.any? { |default| route.defaults[:controller].start_with?(default) }
           return false if RAILS_DEFAULT_PATHS.any? { |path| route.path.spec.to_s.include?(path) }
           return false unless route.path.spec.to_s.start_with?(OasRails.config.api_path)
+          return false if ignore_custom_actions(route)
 
           true
         end
@@ -119,6 +120,27 @@ module OasRails
             controller_class.instance_methods.include?(action_name.to_sym)
           end
         end
+
+        # Ignore user-specified paths in initializer configuration.
+        # Sanitize api_path by removing the "/" if it starts with that, and adding "/" if it ends without that.
+        # Support controller name only to ignore all controller actions.
+        # Support ignoring "controller#action"
+        # Ignoring "controller#action" AND "api_path/controller#action"
+        def ignore_custom_actions(route)
+          api_path = "#{OasRails.config.api_path.sub(%r{\A/}, '')}/".sub(%r{/+$}, '/')
+          ignored_actions = OasRails.config.ignored_actions.flat_map do |custom_route|
+            if custom_route.start_with?(api_path)
+              [custom_route]
+            else
+              ["#{api_path}#{custom_route}", custom_route]
+            end
+          end
+
+          controller_action = "#{route.defaults[:controller]}##{route.defaults[:action]}"
+          controller_only = route.defaults[:controller]
+
+          ignored_actions.include?(controller_action) || ignored_actions.include?(controller_only)
+        end
       end
     end
   end

data/lib/oas_rails/version.rb

@@ -1,3 +1,3 @@
 module OasRails
-  VERSION = "0.7.0"
+  VERSION = "0.8.1"
 end

data/lib/oas_rails/yard/oas_rails_factory.rb

@@ -15,7 +15,7 @@ module OasRails
       # @param text [String] The tag text to parse.
       # @return [RequestBodyExampleTag] The parsed request body example tag object.
       def parse_tag_with_request_body_example(tag_name, text)
-        description, _, hash = extract_description_type_and_content(text, process_content: true)
+        description, _, hash = extract_description_type_and_content(text, process_content: true, expresion: /^(.*?)\[([^\]]*)\](.*)$/m)
         RequestBodyExampleTag.new(tag_name, description, content: hash)
       end
 
@@ -52,8 +52,8 @@ module OasRails
       # @param text [String] The text to parse.
       # @param process_content [Boolean] Whether to evaluate the content as a hash.
       # @return [Array] An array containing the description, type, and content or remaining text.
-      def extract_description_type_and_content(text, process_content: false)
-        match = text.match(/^(.*?)\s*\[(.*)\]\s*(.*)$/)
+      def extract_description_type_and_content(text, process_content: false, expresion: /^(.*?)\s*\[(.*)\]\s*(.*)$/)
+        match = text.match(expresion)
         raise ArgumentError, "Invalid tag format: #{text}" if match.nil?
 
         description = match[1].strip

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: oas_rails
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.1
 platform: ruby
 authors:
 - a-chacon
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-08-27 00:00:00.000000000 Z
+date: 2024-10-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: method_source