oas_rails 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9e40d4f8c810e300bbccaf190fd5143e5be804d2d30f1e86393e0478055965f
-  data.tar.gz: 0b6de20a5280115b3550d950da6e26d8424f4d52cc15d6f46f5272224831904e
+  metadata.gz: 785755b5aed419ca89dc279c2965e5de19cc32bfcbd444a6cb2d25da2704fc8c
+  data.tar.gz: 774eac0d5dfb757e23b40c2ce90a1eab929615241109824b86696e481b06ab99
 SHA512:
-  metadata.gz: 832e56a728da8974e07d2e83970f6cfd69b892b2e3a89694e08783520ae50698982a59119cf8497d0f2827ca0a4a443a04b80ef03838fe27c596c8dce30a0c1b
-  data.tar.gz: 63d37307fc03dd0d832586ce9e9ae4bdbc1f5480b7624991b7d1aa44323bb1f94c86ccd94a523b31e67b0f3f91fb08cfed00793529294c071192b7079bd4a641
+  metadata.gz: 58ce0d42fa52b4bbc2c2d5c3bf81e3f23f0e859c62eb2145b63376873ca405f8ee6325b2c447a28b2cd4abd94e74af96986de96fc5ab2c5422b0a8e80a3e83a9
+  data.tar.gz: 537809a2b7dc85e3d66d1d0c06fd677527e06cc6fb5ba390189cc909dc8c912511677ad5686904e0636254b7d78a79cec85bff7ac4a1ae49a2e7c330a7a87aaf

data/README.md

@@ -39,6 +39,7 @@ The goal is to minimize the effort required to create comprehensive documentatio
   - [Tag Information](#tag-information)
   - [Optional Settings](#optional-settings)
   - [Authentication Settings](#authentication-settings)
+  - [Default Responses (Errors)](#default-responses)
 - [Usage](#usage)
   - [Documenting Your Endpoints](#documenting-your-endpoints)
   - [Example](#example-of-documented-endpoints)
@@ -110,6 +111,14 @@ Then fill it with your data. Below are the available configuration options:
 - `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.
 
+### Default Errors
+
+- `config.set_default_responses`: Determines whether to add default errors responses to endpoint. Default is `true`.
+
+- `config.possible_default_responses`: Array with possible default errors.(Some will be added depending on the endpoint, example: not_found only works with show/update/delete). Default: [:not_found, :unauthorized, :forbidden]. It should be HTTP status code symbols from the list: `[:not_found, :unauthorized, :forbidden, :internal_server_error, :unprocessable_entity]`
+
+- `config.response_body_of_default`: body for use in default responses. It must be a Hash. Default: { message: String }
+
 ## 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**.

data/app/controllers/oas_rails/oas_rails_controller.rb

@@ -6,7 +6,7 @@ module OasRails
       respond_to do |format|
         format.html
         format.json do
-          render json: Specification.new.to_json, status: :ok
+          render json: OasRails.build.to_json, status: :ok
         end
       end
     end

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

@@ -86,4 +86,15 @@ OasRails.configure do |config|
   #   "in": "header"
   #  }
   # }
+
+  # ###########################
+  # Default Responses (Errors)
+  # ###########################
+
+  # The default responses errors are setted only if the action allow it.
+  # Example, if you add forbidden then it will be added only if the endpoint requires authentication.
+  # Example: not_found will be setted to the endpoint only if the operation is a show/update/destroy action.
+  # config.set_default_responses = true
+  # config.possible_default_responses = [:not_found, :unauthorized, :forbidden]
+  # config.response_body_of_default = { message: String }
 end

data/lib/oas_rails/builders/content_builder.rb

@@ -0,0 +1,55 @@
+module OasRails
+  module Builders
+    class ContentBuilder
+      def initialize(specification, context)
+        @context = context || :incoming
+        @specification = specification
+        @media_type = Spec::MediaType.new(specification)
+      end
+
+      def with_schema(schema)
+        @media_type.schema = @specification.components.add_schema(schema)
+
+        self
+      end
+
+      def with_examples(examples)
+        @media_type.examples = @specification.components.add_example(examples)
+
+        self
+      end
+
+      def with_examples_from_tags(tags)
+        @media_type.examples = @media_type.examples.merge(tags.each_with_object({}).with_index(1) do |(example, result), _index|
+          key = example.text.downcase.gsub(' ', '_')
+          value = {
+            "summary" => example.text,
+            "value" => example.content
+          }
+          result[key] = @specification.components.add_example(value)
+        end)
+
+        self
+      end
+
+      def from_model_class(klass)
+        return self unless klass.ancestors.include? ActiveRecord::Base
+
+        model_schema = EsquemaBuilder.send("build_#{@context}_schema", klass:)
+        model_schema["required"] = []
+        schema = { type: "object", properties: { klass.to_s.downcase => model_schema } }
+        examples = Spec::MediaType.search_for_examples_in_tests(klass, context: @context)
+        @media_type.schema = @specification.components.add_schema(schema)
+        @media_type.examples = @media_type.examples.merge(examples)
+
+        self
+      end
+
+      def build
+        {
+          "application/json": @media_type
+        }
+      end
+    end
+  end
+end

data/lib/oas_rails/builders/operation_builder.rb

@@ -0,0 +1,32 @@
+module OasRails
+  module Builders
+    class OperationBuilder
+      include Extractors::OasRouteExtractor
+
+      def initialize(specification)
+        @specification = specification
+        @operation = Spec::Operation.new(specification)
+      end
+
+      def from_oas_route(oas_route)
+        @operation.summary = extract_summary(oas_route:)
+        @operation.operation_id = extract_operation_id(oas_route:)
+        @operation.description = oas_route.docstring
+        @operation.tags = extract_tags(oas_route:)
+        @operation.security = extract_security(oas_route:)
+        @operation.parameters = ParametersBuilder.new(@specification).from_oas_route(oas_route).build
+        @operation.request_body = RequestBodyBuilder.new(@specification).from_oas_route(oas_route).reference
+        @operation.responses = ResponsesBuilder.new(@specification)
+                                               .from_oas_route(oas_route)
+                                               .add_autodiscovered_responses(oas_route)
+                                               .add_default_responses(oas_route, !@operation.security.empty?).build
+
+        self
+      end
+
+      def build
+        @operation
+      end
+    end
+  end
+end

data/lib/oas_rails/builders/parameter_builder.rb

@@ -0,0 +1,28 @@
+module OasRails
+  module Builders
+    class ParameterBuilder
+      def initialize(specification)
+        @specification = specification
+        @parameter = Spec::Parameter.new(specification)
+      end
+
+      def from_path(path, param)
+        @parameter.name = param
+        @parameter.in = 'path'
+        @parameter.description = "#{param.split('_')[-1].titleize} of existing #{extract_word_before(path, param).singularize}."
+
+        self
+      end
+
+      def extract_word_before(string, param)
+        regex = %r{/(\w+)/\{#{param}\}}
+        match = string.match(regex)
+        match ? match[1] : nil
+      end
+
+      def build
+        @parameter
+      end
+    end
+  end
+end

data/lib/oas_rails/builders/parameters_builder.rb

@@ -0,0 +1,39 @@
+module OasRails
+  module Builders
+    class ParametersBuilder
+      def initialize(specification)
+        @specification = specification
+        @parameters = []
+      end
+
+      def from_oas_route(oas_route)
+        parameters_from_tags(tags: oas_route.docstring.tags(:parameter))
+        oas_route.path_params.try(:map) do |p|
+          @parameters << ParameterBuilder.new(@specification).from_path(oas_route.path, p).build unless @parameters.any? { |param| param.name.to_s == p.to_s }
+        end
+
+        self
+      end
+
+      def parameters_from_tags(tags:)
+        tags.each do |t|
+          parameter = Spec::Parameter.new(@specification)
+          parameter.name = t.name
+          parameter.in = t.location
+          parameter.required = t.required
+          parameter.schema = t.schema
+          parameter.description = t.text
+          @parameters << parameter
+        end
+
+        self
+      end
+
+      def build
+        @parameters.map do |p|
+          @specification.components.add_parameter(p)
+        end
+      end
+    end
+  end
+end

data/lib/oas_rails/builders/path_item_builder.rb

@@ -0,0 +1,22 @@
+module OasRails
+  module Builders
+    class PathItemBuilder
+      def initialize(specification)
+        @specification = specification
+        @path_item = Spec::PathItem.new(specification)
+      end
+
+      def from_path(path, route_extractor: Extractors::RouteExtractor)
+        route_extractor.host_routes_by_path(path).each do |oas_route|
+          @path_item.add_operation(oas_route.verb.downcase, OperationBuilder.new(@specification).from_oas_route(oas_route).build)
+        end
+
+        self
+      end
+
+      def build
+        @path_item
+      end
+    end
+  end
+end

data/lib/oas_rails/builders/request_body_builder.rb

@@ -0,0 +1,60 @@
+module OasRails
+  module Builders
+    class RequestBodyBuilder
+      def initialize(specification)
+        @specification = specification
+        @request_body = Spec::RequestBody.new(specification)
+      end
+
+      def from_oas_route(oas_route)
+        tag_request_body = oas_route.docstring.tags(:request_body).first
+        if tag_request_body.nil? && OasRails.config.autodiscover_request_body
+          detect_request_body(oas_route) if %w[create update].include? oas_route.method
+        elsif !tag_request_body.nil?
+          from_tags(tag: tag_request_body, examples_tags: oas_route.docstring.tags(:request_body_example))
+        end
+
+        self
+      end
+
+      def from_tags(tag:, examples_tags: [])
+        if tag.klass.ancestors.include? ActiveRecord::Base
+          from_model_class(klass: tag.klass, description: tag.text, required: tag.required, examples_tags:)
+        else
+          @request_body.description = tag.text
+          @request_body.content = ContentBuilder.new(@specification, :incoming).with_schema(tag.schema).with_examples_from_tags(examples_tags).build
+          @request_body.required = tag.required
+        end
+
+        self
+      end
+
+      def from_model_class(klass:, **kwargs)
+        @request_body.description = kwargs[:description] || klass.to_s
+        @request_body.content = ContentBuilder.new(@specification, :incoming).from_model_class(klass).with_examples_from_tags(kwargs[:examples_tags] || {}).build
+        @request_body.required = kwargs[:required]
+
+        self
+      end
+
+      def build
+        return {} if @request_body.content == {}
+
+        @request_body
+      end
+
+      def reference
+        return {} if @request_body.content == {}
+
+        @specification.components.add_request_body(@request_body)
+      end
+
+      private
+
+      def detect_request_body(oas_route)
+        klass = oas_route.controller.singularize.camelize.constantize
+        from_model_class(klass:, required: true)
+      end
+    end
+  end
+end

data/lib/oas_rails/builders/response_builder.rb

@@ -0,0 +1,40 @@
+module OasRails
+  module Builders
+    class ResponseBuilder
+      def initialize(specification)
+        @specification = specification
+        @response = Spec::Response.new(specification)
+      end
+
+      def with_description(description)
+        @response.description = description
+
+        self
+      end
+
+      def with_content(content)
+        @response.content = content
+
+        self
+      end
+
+      def with_code(code)
+        @response.code = code
+
+        self
+      end
+
+      def from_tag(tag)
+        @response.code = tag.name.to_i
+        @response.description = tag.text
+        @response.content = ContentBuilder.new(@specification, :outgoing).with_schema(tag.schema).build
+
+        self
+      end
+
+      def build
+        @response
+      end
+    end
+  end
+end

data/lib/oas_rails/builders/responses_builder.rb

@@ -0,0 +1,58 @@
+module OasRails
+  module Builders
+    class ResponsesBuilder
+      def initialize(specification)
+        @specification = specification
+        @responses = Spec::Responses.new(specification)
+      end
+
+      def from_oas_route(oas_route)
+        oas_route.docstring.tags(:response).each do |tag|
+          @responses.add_response(ResponseBuilder.new(@specification).from_tag(tag).build)
+        end
+
+        self
+      end
+
+      def add_autodiscovered_responses(oas_route)
+        return unless OasRails.config.autodiscover_responses
+
+        new_responses = Extractors::RenderResponseExtractor.extract_responses_from_source(@specification, source: oas_route.source_string)
+
+        new_responses.each do |new_response|
+          @responses.add_response(new_response) if @responses.responses[new_response.code].blank?
+        end
+
+        self
+      end
+
+      def add_default_responses(oas_route, security)
+        return unless OasRails.config.set_default_responses
+
+        content = ContentBuilder.new(@specification, :outgoing).with_schema(Utils.hash_to_json_schema(OasRails.config.response_body_of_default)).build
+        common_errors = []
+        common_errors.push(:unauthorized, :forbidden) if security
+
+        case oas_route.method
+        when "show", "update", "destroy"
+          common_errors.push(:not_found)
+        when "create", "index"
+          # possible errors for this methods?
+        end
+
+        (OasRails.config.possible_default_responses & common_errors).each do |e|
+          code = Utils.status_to_integer(e)
+          response = ResponseBuilder.new(@specification).with_code(code).with_description(Utils.get_definition(code)).with_content(content).build
+
+          @responses.add_response(response) if @responses.responses[response.code].blank?
+        end
+
+        self
+      end
+
+      def build
+        @responses
+      end
+    end
+  end
+end

data/lib/oas_rails/configuration.rb

@@ -1,10 +1,19 @@
 module OasRails
   class Configuration
-    attr_accessor :info, :default_tags_from, :autodiscover_request_body, :autodiscover_responses, :api_path, :security_schemas, :authenticate_all_routes_by_default
+    attr_accessor :info,
+                  :default_tags_from,
+                  :autodiscover_request_body,
+                  :autodiscover_responses,
+                  :api_path,
+                  :security_schemas,
+                  :authenticate_all_routes_by_default,
+                  :set_default_responses,
+                  :possible_default_responses,
+                  :response_body_of_default
     attr_reader :servers, :tags, :security_schema
 
     def initialize
-      @info = Info.new
+      @info = Spec::Info.new
       @servers = default_servers
       @tags = []
       @swagger_version = '3.1.0'
@@ -15,6 +24,9 @@ module OasRails
       @authenticate_all_routes_by_default = true
       @security_schema = nil
       @security_schemas = {}
+      @set_default_responses = true
+      @possible_default_responses = [:not_found, :unauthorized, :forbidden]
+      @response_body_of_default = { message: String }
     end
 
     def security_schema=(value)
@@ -24,15 +36,15 @@ module OasRails
     end
 
     def default_servers
-      [Server.new(url: "http://localhost:3000", description: "Rails Default Development Server")]
+      [Spec::Server.new(url: "http://localhost:3000", description: "Rails Default Development Server")]
     end
 
     def servers=(value)
-      @servers = value.map { |s| Server.new(url: s[:url], description: s[:description]) }
+      @servers = value.map { |s| Spec::Server.new(url: s[:url], description: s[:description]) }
     end
 
     def tags=(value)
-      @tags = value.map { |t| Tag.new(name: t[:name], description: t[:description]) }
+      @tags = value.map { |t| Spec::Tag.new(name: t[:name], description: t[:description]) }
     end
 
     def excluded_columns_incoming

data/lib/oas_rails/extractors/oas_route_extractor.rb

@@ -0,0 +1,66 @@
+module OasRails
+  module Extractors
+    module OasRouteExtractor
+      def extract_summary(oas_route:)
+        oas_route.docstring.tags(:summary).first.try(:text) || generate_crud_name(oas_route.method, oas_route.controller.downcase) || "#{oas_route.verb} #{oas_route.path}"
+      end
+
+      def extract_operation_id(oas_route:)
+        "#{oas_route.method}#{oas_route.path.gsub('/', '_').gsub(/[{}]/, '')}"
+      end
+
+      def extract_tags(oas_route:)
+        tags = oas_route.docstring.tags(:tags).first
+        if tags.nil?
+          default_tags(oas_route:)
+        else
+          tags.text.split(",").map(&:strip).map(&:titleize)
+        end
+      end
+
+      def default_tags(oas_route:)
+        tags = []
+        if OasRails.config.default_tags_from == "namespace"
+          tag = oas_route.path.split('/').reject(&:empty?).first.try(:titleize)
+          tags << tag unless tag.nil?
+        else
+          tags << oas_route.controller.titleize
+        end
+        tags
+      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
+
+      private
+
+      def generate_crud_name(method, controller)
+        controller_name = controller.to_s.underscore.humanize.downcase.pluralize
+
+        case method.to_sym
+        when :index
+          "List #{controller_name}"
+        when :show
+          "View #{controller_name.singularize}"
+        when :create
+          "Create new #{controller_name.singularize}"
+        when :update
+          "Update #{controller_name.singularize}"
+        when :destroy
+          "Delete #{controller_name.singularize}"
+        end
+      end
+    end
+  end
+end

data/lib/oas_rails/extractors/render_response_extractor.rb

@@ -7,12 +7,11 @@ module OasRails
         #
         # @param source [String] The source string containing render calls.
         # @return [Array<Response>] An array of Response objects extracted from the source.
-        def extract_responses_from_source(source:)
+        def extract_responses_from_source(specification, source:)
           render_calls = extract_render_calls(source)
+          return [Builders::ResponseBuilder.new(specification).with_description("No content").with_code(204).build] if render_calls.empty?
 
-          return [Response.new(code: 204, description: "No Content", content: {})] if render_calls.empty?
-
-          render_calls.map { |render_content, status| process_render_content(render_content.strip, status) }
+          render_calls.map { |render_content, status| process_render_content(specification, render_content.strip, status) }
         end
 
         private
@@ -30,14 +29,12 @@ module OasRails
         # @param content [String] The content extracted from the render call.
         # @param status [String] The status code associated with the render call.
         # @return [Response] A Response object based on the processed content and status.
-        def process_render_content(content, status)
+        def process_render_content(specification, content, status)
           schema, examples = build_schema_and_examples(content)
-          status_int = status_to_integer(status)
-          Response.new(
-            code: status_int,
-            description: status_code_to_text(status_int),
-            content: { "application/json": MediaType.new(schema:, examples:) }
-          )
+          status_int = Utils.status_to_integer(status)
+          content = Builders::ContentBuilder.new(specification, :outgoing).with_schema(schema).with_examples(examples).build
+
+          Builders::ResponseBuilder.new(specification).with_code(status_int).with_description(Utils.status_code_to_text(status_int)).with_content(content).build
         end
 
         # Builds schema and examples based on the content type.
@@ -84,8 +81,9 @@ module OasRails
         # @return [Array<Hash, Hash>] An array where the first element is the schema and the second is the examples.
         def build_singular_model_schema_and_examples(_maybe_a_model, errors, klass, schema)
           if errors.nil?
-            [schema, MediaType.search_for_examples_in_tests(klass:, context: :outgoing)]
+            [schema, Spec::MediaType.search_for_examples_in_tests(klass, context: :outgoing)]
           else
+            # TODO: this is not building the real schema.
             [
               {
                 type: "object",
@@ -112,7 +110,7 @@ module OasRails
         # @param schema [Hash] The schema for the model.
         # @return [Array<Hash, Hash>] An array where the first element is the schema and the second is the examples.
         def build_array_model_schema_and_examples(maybe_a_model, klass, schema)
-          examples = { maybe_a_model => { value: MediaType.search_for_examples_in_tests(klass:, context: :outgoing).values.map { |p| p.dig(:value, maybe_a_model.singularize.to_sym) } } }
+          examples = { maybe_a_model => { value: Spec::MediaType.search_for_examples_in_tests(klass, context: :outgoing).values.map { |p| p.dig(:value, maybe_a_model.singularize.to_sym) } } }
           [{ type: "array", items: schema }, examples]
         end
 
@@ -144,29 +142,6 @@ module OasRails
 
           structure
         end
-
-        # Converts a status symbol or string to an integer.
-        #
-        # @param status [String, Symbol, nil] The status to convert.
-        # @return [Integer] The status code as an integer.
-        def status_to_integer(status)
-          return 200 if status.nil?
-
-          if status.to_s =~ /^\d+$/
-            status.to_i
-          else
-            status = "unprocessable_content" if status == "unprocessable_entity"
-            Rack::Utils::SYMBOL_TO_STATUS_CODE[status.to_sym]
-          end
-        end
-
-        # Converts a status code to its corresponding text description.
-        #
-        # @param status_code [Integer] The status code.
-        # @return [String] The text description of the status code.
-        def status_code_to_text(status_code)
-          Rack::Utils::HTTP_STATUS_CODES[status_code] || "Unknown Status Code"
-        end
       end
     end
   end

data/lib/oas_rails/oas_route.rb

@@ -41,10 +41,5 @@ module OasRails
     def controller_path_extractor(controller)
       Rails.root.join("app/controllers/#{controller}_controller.rb").to_s
     end
-
-    def detect_request_body
-      klass = @controller.singularize.camelize.constantize
-      RequestBody.from_model_class(klass:, required: true)
-    end
   end
 end