oas_rails 0.1.1 → 0.2.1

data/README.md

@@ -1,5 +1,6 @@
 ![Gem Version](https://img.shields.io/gem/v/oas_rails)
 ![GitHub License](https://img.shields.io/github/license/a-chacon/oas_rails)
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/a-chacon/oas_rails/.github%2Fworkflows%2Frubyonrails.yml)
 
 # Open API Specification For Rails
 
@@ -39,15 +40,15 @@ The goal is to minimize the effort required to create comprehensive documentatio
 
 2. Execute:
 
-```bash
-bundle
-```
+   ```bash
+   bundle
+   ```
 
 3. Mount the engine in your config/routes.rb file
 
-```ruby
-mount OasRails::Engine => '/docs'
-```
+   ```ruby
+   mount OasRails::Engine => '/docs'
+   ```
 
 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.
 
@@ -57,7 +58,7 @@ You'll now have **basic documentation** based on your routes and automatically g
 
 You can easy create the initializer file with:
 
-```
+```bash
 rails generate oas_rails:config
 ```
 
@@ -65,6 +66,89 @@ Then complete the created file with your data.
 
 **Almost every description in a OAS file support simple markdown**
 
+## Configuration
+
+To configure OasRails, edit the `config/initializers/oas_rails.rb` file. Below are the available configuration options:
+
+### Basic Information about the API
+
+- `config.info.title`: The title of your API documentation.
+- `config.info.summary`: A brief summary of your API.
+- `config.info.description`: A detailed description of your API. This can include markdown formatting and will be displayed prominently in your documentation.
+- `config.info.contact.name`: The name of the contact person or organization.
+- `config.info.contact.email`: The contact email address.
+- `config.info.contact.url`: The URL for more information or support.
+
+### Servers Information
+
+- `config.servers`: An array of server objects, each containing `url` and `description` keys. For more details, refer to the [OpenAPI Specification](https://spec.openapis.org/oas/latest.html#server-object).
+
+### Tag Information
+
+- `config.tags`: An array of tag objects, each containing `name` and `description` keys. For more details, refer to the [OpenAPI Specification](https://spec.openapis.org/oas/latest.html#tag-object).
+
+### Optional Settings
+
+- `config.default_tags_from`: Determines the source of default tags for operations. Can be set to `:namespace` or `:controller`.
+- `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.
+
+### Authentication Settings
+
+- `config.authenticate_all_routes_by_default`: Determines whether to authenticate all routes by default. Default is `true`.
+- `config.security_schema`: The default security schema used for authentication. Choose a predefined security schema from `[:api_key_cookie, :api_key_header, :api_key_query, :basic, :bearer, :bearer_jwt, :mutual_tls]`.
+- `config.security_schemas`: Custom security schemas. Follow the [OpenAPI Specification](https://spec.openapis.org/oas/latest.html#security-scheme-object) for defining these schemas.
+
+## 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:
+
+### 1. Using Basic Authentication
+
+Use basic authentication to protect the OasRails endpoint. You can set this up in an initializer:
+
+```ruby
+# config/initializers/oas_rails.rb
+OasRails::Engine.middleware.use(Rack::Auth::Basic) do |username, password|
+  ActiveSupport::SecurityUtils.secure_compare(Rails.application.credentials.oas_rails_username, username) &
+    ActiveSupport::SecurityUtils.secure_compare(Rails.application.credentials.oas_rails_password, password)
+end
+```
+
+### 2. Using Devise's `authenticate` Helper
+
+You can use Devise's `authenticate` helper to restrict access to the OasRails endpoint. For example, you can allow only admin users to access the endpoint:
+
+```ruby
+# config/routes.rb
+# ...
+authenticate :user, ->(user) { user.admin? } do
+  mount OasRails::Engine, at: '/docs'
+end
+```
+
+### 3. Custom Authentication
+
+To support custom authentication, you can extend the OasRails' ApplicationController using a hook. This allows you to add custom before actions to check for specific user permissions:
+
+```ruby
+# config/initializers/oas_rails.rb
+
+ActiveSupport.on_load(:oas_rails_application_controller) do
+  # context here is OasRails::ApplicationController
+
+  before_action do
+    raise ActionController::RoutingError.new('Not Found') unless current_user&.admin?
+  end
+
+  def current_user
+    # Load the current user
+    User.find(session[:user_id]) # Adjust according to your authentication logic
+  end
+end
+```
+
 ## Documenting Your Endpoints
 
 Almost every description in an OAS file supports simple markdown. The following tags are available for documenting your endpoints:
@@ -142,6 +226,30 @@ Tags your endpoints. You can complete the tag documentation in the initializer f
 
 </details>
 
+<details>
+<summary style="font-weight: bold; font-size: 1.2em;">@no_auth</summary>
+
+**Structure**: `@no_auth`
+
+This tag will remove any security requirement from the endpoint. Useful when most of your endpoints require authentication and only a few do not.(Ex: Login, Registration...)
+
+**Example**:
+`# @no_auth`
+
+</details>
+
+<details>
+<summary style="font-weight: bold; font-size: 1.2em;">@auth</summary>
+
+**Structure**: `@auth [types]`
+
+This tag will set which security mechanisms can be used for the endpoint. The security mechanisms MUST be defined previously in the initializer file.
+
+**Example**:
+`# @auth [bearer, basic]`
+
+</details>
+
 You can use these tags in your controller methods to enhance the automatically generated documentation. Remember to use markdown formatting in your descriptions for better readability in the generated OAS document.
 
 ### Example of documented endpoints
@@ -160,6 +268,7 @@ class UsersController < ApplicationController
   end
 
   # @summary Get a user by id.
+  # @auth [bearer]
   #
   # This method show a User by ID. The id must exist of other way it will be returning a **`404`**.
   #
@@ -172,6 +281,7 @@ class UsersController < ApplicationController
   end
 
   # @summary Create a User
+  # @no_auth
   #
   # @request_body The user to be created. At least include an `email`. [User!]
   # @request_body_example basic user [Hash] {user: {name: "Luis", email: "luis@gmail.ocom"}}
@@ -234,12 +344,12 @@ Contributions are what make the open source community such an amazing place to l
 ### Roadmap and Ideas for Improvement
 
 - Clean, document and structure the code
-- Support documentation of authentication methods
+- [x] Support documentation of authentication methods
 - Define Global Tags/Configuration (e.g., common responses like 404 errors)
 - Post-process the JSON and replace common objects with references to components
 - Create a temporary file with the JSON in production mode to avoid rebuilding it on every request
 - Create tags for popular gems used in APIs (e.g., a `@pagy` tag for common pagination parameters)
-- Add basic authentication to OAS and UI for security reasons
+- [x] Add basic authentication to OAS and UI for security reasons (Solution documented, not need to be managed by the engine)
 - Implement ability to define OAS by namespaces (e.g., generate OAS for specific routes like `/api` or separate versions V1 and V2)
 
 ## License

data/app/controllers/oas_rails/application_controller.rb

@@ -1,4 +1,5 @@
 module OasRails
   class ApplicationController < ActionController::Base
+    protect_from_forgery with: :exception
   end
 end

data/app/controllers/oas_rails/oas_rails_controller.rb

@@ -1,9 +1,12 @@
 module OasRails
   class OasRailsController < ApplicationController
-    def index; end
-
-    def oas
-      render json: Specification.new.to_json, status: :ok
+    def index
+      respond_to do |format|
+        format.html
+        format.json do
+          render json: Specification.new.to_json, status: :ok
+        end
+      end
     end
   end
 end

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

@@ -1 +1 @@
-<rapi-doc spec-url = "<%= main_app.oas_rails_path %>/oas" theme = "dark" text-color="#f9f9f9" show-header = 'false'> </rapi-doc>
+<rapi-doc spec-url = "<%= main_app.oas_rails_path %>.json" theme = "dark" text-color="#f9f9f9" show-header = 'false'> </rapi-doc>

data/config/routes.rb

@@ -1,4 +1,3 @@
 OasRails::Engine.routes.draw do
-  root 'oas_rails#index'
-  get '/oas', to: 'oas_rails#oas'
+  get '(.:format)', to: 'oas_rails#index'
 end

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

@@ -1,5 +1,6 @@
 # config/initializers/oas_rails.rb
 OasRails.configure do |config|
+  # Basic Information about the API
   config.info.title = 'OasRails'
   config.info.summary = 'OasRails: Automatic Interactive API Documentation for Rails'
   config.info.description = <<~HEREDOC
@@ -34,17 +35,55 @@ OasRails.configure do |config|
     Explore your API documentation and enjoy the power of OasRails!
 
     For more information and advanced usage, visit the [OasRails GitHub repository](https://github.com/a-chacon/oas_rails).
-
-
   HEREDOC
   config.info.contact.name = 'a-chacon'
   config.info.contact.email = 'andres.ch@proton.me'
   config.info.contact.url = 'https://a-chacon.com'
+
+  # Servers Information. For more details follow: https://spec.openapis.org/oas/latest.html#server-object
   config.servers = [{ url: 'http://localhost:3000', description: 'Local' }]
+
+  # Tag Information. For more details follow: https://spec.openapis.org/oas/latest.html#tag-object
   config.tags = [{ name: "Users", description: "Manage the `amazing` Users table." }]
 
-  # config.default_tags_from = :namespace # Could be: :namespace or :controller
-  # config.autodiscover_request_body = true # Try to get request body for create and update methods based on the controller name.
-  # config.autodiscover_responses = true # Looks for renders in your source code and try to generate the responses.
-  # config.api_path = "/" # set this config if your api is in a different namespace other than /
+  # Optional Settings (Uncomment to use)
+
+  # Extract default tags of operations from namespace or controller. Can be set to :namespace or :controller
+  # config.default_tags_from = :namespace
+
+  # Automatically detect request bodies for create/update methods
+  # Default: true
+  # config.autodiscover_request_body = false
+
+  # Automatically detect responses from controller renders
+  # Default: true
+  # config.autodiscover_responses = false
+
+  # API path configuration if your API is under a different namespace
+  # config.api_path = "/"
+
+  # #######################
+  # Authentication Settings
+  # #######################
+
+  # Whether to authenticate all routes by default
+  # Default is true; set to false if you don't want all routes to include secutrity schemas by default
+  # config.authenticate_all_routes_by_default = true
+
+  # Default security schema used for authentication
+  # Choose a predefined security schema
+  # [:api_key_cookie, :api_key_header, :api_key_query, :basic, :bearer, :bearer_jwt, :mutual_tls]
+  # config.security_schema = :bearer
+
+  # Custom security schemas
+  # You can uncomment and modify to use custom security schemas
+  # Please follow the documentation: https://spec.openapis.org/oas/latest.html#security-scheme-object
+  #
+  # config.security_schemas = {
+  #  bearer:{
+  #   "type": "apiKey",
+  #   "name": "api_key",
+  #   "in": "header"
+  #  }
+  # }
 end

data/lib/oas_rails/configuration.rb

@@ -1,17 +1,26 @@
 module OasRails
   class Configuration
-    attr_accessor :info, :default_tags_from, :autodiscover_request_body, :autodiscover_responses, :api_path
-    attr_reader :servers, :tags
+    attr_accessor :info, :default_tags_from, :autodiscover_request_body, :autodiscover_responses, :api_path, :security_schemas, :authenticate_all_routes_by_default
+    attr_reader :servers, :tags, :security_schema
 
-    def initialize(**kwargs)
+    def initialize
       @info = Info.new
-      @servers = kwargs[:servers] || default_servers
+      @servers = default_servers
       @tags = []
       @swagger_version = '3.1.0'
       @default_tags_from = "namespace"
       @autodiscover_request_body = true
       @autodiscover_responses = true
       @api_path = "/"
+      @authenticate_all_routes_by_default = true
+      @security_schema = nil
+      @security_schemas = {}
+    end
+
+    def security_schema=(value)
+      return unless (security_schema = DEFAULT_SECURITY_SCHEMES[value])
+
+      @security_schemas = { value => security_schema }
     end
 
     def default_servers
@@ -26,4 +35,45 @@ module OasRails
       @tags = value.map { |t| Tag.new(name: t[:name], description: t[:description]) }
     end
   end
+
+  DEFAULT_SECURITY_SCHEMES = {
+    api_key_cookie: {
+      type: "apiKey",
+      in: "cookie",
+      name: "api_key",
+      description: "An API key that will be supplied in a named cookie."
+    },
+    api_key_header: {
+      type: "apiKey",
+      in: "header",
+      name: "X-API-Key",
+      description: "An API key that will be supplied in a named header."
+    },
+    api_key_query: {
+      type: "apiKey",
+      in: "query",
+      name: "apiKey",
+      description: "An API key that will be supplied in a named query parameter."
+    },
+    basic: {
+      type: "http",
+      scheme: "basic",
+      description: "Basic auth that takes a base64'd combination of `user:password`."
+    },
+    bearer: {
+      type: "http",
+      scheme: "bearer",
+      description: "A bearer token that will be supplied within an `Authorization` header as `bearer <token>`."
+    },
+    bearer_jwt: {
+      type: "http",
+      scheme: "bearer",
+      bearerFormat: "JWT",
+      description: "A bearer token that will be supplied within an `Authorization` header as `bearer <token>`. In this case, the format of the token is specified as JWT."
+    },
+    mutual_tls: {
+      type: "mutualTLS",
+      description: "Requires a specific mutual TLS certificate to use when making an HTTP request."
+    }
+  }.freeze
 end

data/lib/oas_rails/media_type.rb

@@ -21,7 +21,7 @@ module OasRails
       end
 
       def search_for_examples_in_tests(klass:)
-        case OasRails.detect_test_framework
+        case Utils.detect_test_framework
         when :factory_bot
           {}
           # TODO: create examples with FactoryBot

data/lib/oas_rails/oas_base.rb

@@ -13,7 +13,8 @@ module OasRails
                             value
                           end
 
-        hash[camel_case_key] = processed_value unless (processed_value.is_a?(Hash) || processed_value.is_a?(Array)) && processed_value.empty?
+        # hash[camel_case_key] = processed_value unless (processed_value.is_a?(Hash) || processed_value.is_a?(Array)) && processed_value.empty?
+        hash[camel_case_key] = processed_value
       end
       hash
     end

data/lib/oas_rails/oas_route.rb

@@ -59,7 +59,7 @@ module OasRails
         schema = {}
         begin
           schema = if content.start_with?('{')
-                     OasRails.hash_to_json_schema(parse_hash_structure(content))
+                     Utils.hash_to_json_schema(parse_hash_structure(content))
                    else
                      # It's likely a variable or method call
                      maybe_a_model, errors = content.gsub('@', "").split(".")

data/lib/oas_rails/operation.rb

@@ -1,6 +1,6 @@
 module OasRails
   class Operation < OasBase
-    attr_accessor :tags, :summary, :description, :operation_id, :parameters, :method, :docstring, :request_body, :responses
+    attr_accessor :tags, :summary, :description, :operation_id, :parameters, :method, :docstring, :request_body, :responses, :security
 
     def initialize(method:, summary:, operation_id:, **kwargs)
       super()
@@ -12,6 +12,7 @@ module OasRails
       @parameters = kwargs[:parameters] || []
       @request_body = kwargs[:request_body] || {}
       @responses = kwargs[:responses] || {}
+      @security = kwargs[:security] || []
     end
 
     class << self
@@ -23,7 +24,8 @@ module OasRails
         parameters = extract_parameters(oas_route:)
         request_body = extract_request_body(oas_route:)
         responses = extract_responses(oas_route:)
-        new(method: oas_route.verb.downcase, summary:, operation_id:, tags:, description:, parameters:, request_body:, responses:)
+        security = extract_security(oas_route:)
+        new(method: oas_route.verb.downcase, summary:, operation_id:, tags:, description:, parameters:, request_body:, responses:, security:)
       end
 
       def extract_summary(oas_route:)
@@ -112,6 +114,20 @@ module OasRails
         responses
       end
 
+      def extract_security(oas_route:)
+        return [] if oas_route.docstring.tags(:no_auth).any?
+
+        if (methods = oas_route.docstring.tags(:auth).first)
+          OasRails.config.security_schemas.keys.map { |key| { key => [] } }.select do |schema|
+            methods.types.include?(schema.keys.first.to_s)
+          end
+        elsif OasRails.config.authenticate_all_routes_by_default
+          OasRails.config.security_schemas.keys.map { |key| { key => [] } }
+        else
+          []
+        end
+      end
+
       def external_docs; end
     end
   end

data/lib/oas_rails/route_extractor.rb

@@ -76,13 +76,36 @@ module OasRails
       end
 
       def valid_api_route?(route)
-        return false if route.defaults[:controller].nil?
+        return false unless valid_route_implementation?(route)
         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)
 
         true
       end
+
+      # Checks if a route has a valid implementation.
+      #
+      # This method verifies that both the controller and the action specified
+      # in the route exist. It checks if the controller class is defined and
+      # if the action method is implemented within that controller.
+      #
+      # @param route [ActionDispatch::Journey::Route] The route to check.
+      # @return [Boolean] true if both the controller and action exist, false otherwise.
+      def valid_route_implementation?(route)
+        controller_name = route.defaults[:controller]&.camelize
+        action_name = route.defaults[:action]
+
+        return false if controller_name.blank? || action_name.blank?
+
+        controller_class = "#{controller_name}Controller".safe_constantize
+
+        if controller_class.nil?
+          false
+        else
+          controller_class.instance_methods.include?(action_name.to_sym)
+        end
+      end
     end
   end
 end

data/lib/oas_rails/specification.rb

@@ -15,28 +15,48 @@ module OasRails
       {}
     end
 
+    # Create the Base of the OAS hash.
+    # @see https://spec.openapis.org/oas/latest.html#schema
     def base_spec
       {
         openapi: '3.1.0',
         info: OasRails.config.info.to_spec,
         servers: OasRails.config.servers.map(&:to_spec),
-        paths: paths_spec,
-        components: components_spec,
-        security: [],
+        paths:,
+        components:,
+        security:,
         tags: OasRails.config.tags.map(&:to_spec),
         externalDocs: {}
       }
     end
 
-    def paths_spec
+    # Create the Security Requirement Object.
+    # @see https://spec.openapis.org/oas/latest.html#security-requirement-object
+    def security
+      return [] unless OasRails.config.authenticate_all_routes_by_default
+
+      OasRails.config.security_schemas.map { |key, _| { key => [] } }
+    end
+
+    # Create the Paths Object For the Root of the OAS.
+    # @see https://spec.openapis.org/oas/latest.html#paths-object
+    def paths
       Paths.from_string_paths(string_paths: RouteExtractor.host_paths).to_spec
     end
 
-    def components_spec
+    # Created the Components Object For the Root of the OAS.
+    # @see https://spec.openapis.org/oas/latest.html#components-object
+    def components
       {
-        schemas: {}, parameters: {}, securitySchemas: {}, requestBodies: {}, responses: {},
+        schemas: {}, parameters: {}, securitySchemes: security_schemas, requestBodies: {}, responses: {},
         headers: {}, examples: {}, links: {}, callbacks: {}
       }
     end
+
+    # Create the Security Schemas Array inside components field of the OAS.
+    # @see https://spec.openapis.org/oas/latest.html#security-scheme-object
+    def security_schemas
+      OasRails.config.security_schemas
+    end
   end
 end

data/lib/oas_rails/utils.rb

@@ -0,0 +1,66 @@
+module OasRails
+  module Utils
+    TYPE_MAPPING = {
+      'String' => 'string',
+      'Integer' => 'number',
+      'Float' => 'number',
+      'TrueClass' => 'boolean',
+      'FalseClass' => 'boolean',
+      'Boolean' => 'boolean',
+      'NilClass' => 'null',
+      'Hash' => 'object',
+      'Object' => 'object',
+      'DateTime' => 'string'
+    }.freeze
+
+    class << self
+      # Method for detect test framework of the Rails App
+      # It is used for generate examples in operations
+      def detect_test_framework
+        if defined?(FactoryBot)
+          :factory_bot
+        elsif ActiveRecord::Base.connection.table_exists?('ar_internal_metadata')
+          :fixtures
+        else
+          :unknown
+        end
+      end
+
+      def type_to_schema(type_string)
+        if type_string.start_with?('Array<')
+          inner_type = type_string[/Array<(.+)>$/, 1]
+          {
+            "type" => "array",
+            "items" => type_to_schema(inner_type)
+          }
+        else
+          { "type" => TYPE_MAPPING.fetch(type_string, 'string') }
+        end
+      end
+
+      def hash_to_json_schema(hash)
+        {
+          type: 'object',
+          properties: hash_to_properties(hash),
+          required: []
+        }
+      end
+
+      def hash_to_properties(hash)
+        hash.transform_values do |value|
+          if value.is_a?(Hash)
+            hash_to_json_schema(value)
+          elsif value.is_a?(Class)
+            { type: ruby_type_to_json_type(value.name) }
+          else
+            { type: ruby_type_to_json_type(value.class.name) }
+          end
+        end
+      end
+
+      def ruby_type_to_json_type(ruby_type)
+        TYPE_MAPPING.fetch(ruby_type, 'string')
+      end
+    end
+  end
+end

data/lib/oas_rails/version.rb

@@ -1,3 +1,3 @@
 module OasRails
-  VERSION = "0.1.1"
+  VERSION = "0.2.1"
 end

data/lib/oas_rails/yard/oas_yard_factory.rb

@@ -55,7 +55,7 @@ module OasRails
 
             begin
               hash = eval(hash_string)
-              hash = OasRails.hash_to_json_schema(hash)
+              hash = Utils.hash_to_json_schema(hash)
             rescue StandardError
               hash = {}
             end
@@ -94,7 +94,7 @@ module OasRails
           text = match[1].strip
           name, location = parse_position_name(text)
           type, required = parse_type(match[2].strip)
-          schema = OasRails.type_to_schema(type)
+          schema = Utils.type_to_schema(type)
 
           ParameterTag.new(tag_name, name, match[3].strip, schema, location, required:)
         else
@@ -109,7 +109,7 @@ module OasRails
 
           begin
             hash = parse_str_to_hash(match[3].strip)
-            hash = OasRails.hash_to_json_schema(hash)
+            hash = Utils.hash_to_json_schema(hash)
           rescue StandardError
             hash = {}
           end