rest_framework 1.0.0.beta2 → 1.0.0

data/lib/rest_framework/mixins/base_controller_mixin.rb

@@ -11,7 +11,7 @@ module RESTFramework::Mixins::BaseControllerMixin
     title: nil,
     description: nil,
     version: nil,
-    inflect_acronyms: ["ID", "IDs", "REST", "API", "APIs"].freeze,
+    inflect_acronyms: [ "ID", "IDs", "REST", "API", "APIs" ].freeze,
     openapi_include_children: false,
 
     # Options related to serialization.
@@ -38,14 +38,14 @@ module RESTFramework::Mixins::BaseControllerMixin
 
   # Default action for API root.
   def root
-    render_api({message: "This is the API root."})
+    render(api: { message: "This is the API root." })
   end
 
   module ClassMethods
     # By default, this is the name of the controller class, titleized and with any custom inflection
     # acronyms applied.
     def get_title
-      return self.title || RESTFramework::Utils.inflect(
+      self.title || RESTFramework::Utils.inflect(
         self.name.demodulize.chomp("Controller").titleize(keep_id_suffix: true),
         self.inflect_acronyms,
       )
@@ -53,10 +53,7 @@ module RESTFramework::Mixins::BaseControllerMixin
 
     # Get a label from a field/column name, titleized and inflected.
     def label_for(s)
-      return RESTFramework::Utils.inflect(
-        s.to_s.titleize(keep_id_suffix: true),
-        self.inflect_acronyms,
-      )
+      RESTFramework::Utils.inflect(s.to_s.titleize(keep_id_suffix: true), self.inflect_acronyms)
     end
 
     # Define any behavior to execute at the end of controller definition.
@@ -71,50 +68,58 @@ module RESTFramework::Mixins::BaseControllerMixin
     end
     # :nocov:
 
-    def openapi_paths(routes, tag)
-      response_content_types = [
+    def openapi_response_content_types
+      @openapi_response_content_types ||= [
         "text/html",
         self.serialize_to_json ? "application/json" : nil,
         self.serialize_to_xml ? "application/xml" : nil,
       ].compact
-      request_content_types = [
+    end
+
+    def openapi_request_content_types
+      @openapi_request_content_types ||= [
         "application/json",
-        "application/xml",
         "application/x-www-form-urlencoded",
         "multipart/form-data",
       ]
+    end
+
+    def openapi_paths(routes, tag)
+      resp_cts = self.openapi_response_content_types
+      req_cts = self.openapi_request_content_types
 
-      return routes.group_by { |r| r[:concat_path] }.map { |concat_path, routes|
+      routes.group_by { |r| r[:concat_path] }.map { |concat_path, routes|
         [
           concat_path.gsub(/:([0-9A-Za-z_-]+)/, "{\\1}"),
           routes.map { |route|
-            metadata = route[:route].defaults[:metadata] || {}
-            summary = metadata[:label].presence || self.label_for(route[:action])
-            description = metadata[:description].presence
-            remaining_metadata = metadata.except(:label, :description).presence
-
-            [
-              route[:verb].downcase,
-              {
-                tags: [tag],
-                summary: summary,
-                description: description,
-                responses: {
-                  200 => {
-                    content: response_content_types.map { |ct|
-                      [ct, {}]
-                    }.to_h,
-                    description: "",
-                  },
-                },
-                requestBody: route[:verb].in?(["GET", "DELETE", "OPTIONS", "TRACE"]) ? nil : {
-                  content: request_content_types.map { |ct|
-                    [ct, {}]
-                  }.to_h,
-                },
-                "x-rrf-metadata": remaining_metadata,
-              }.compact,
-            ]
+            metadata = RESTFramework::ROUTE_METADATA[route[:path]] || {}
+            summary = metadata.delete(:label).presence || self.label_for(route[:action])
+            description = metadata.delete(:description).presence
+            extra_action = RESTFramework::EXTRA_ACTION_ROUTES.include?(route[:path])
+            error_response = { "$ref" => "#/components/responses/BadRequest" }
+            not_found_response = { "$ref" => "#/components/responses/NotFound" }
+            spec = { tags: [ tag ], summary: summary, description: description }.compact
+
+            # All routes should have a successful response.
+            spec[:responses] = {
+              200 => { content: resp_cts.map { |ct| [ ct, {} ] }.to_h, description: "Success" },
+            }
+
+            # Builtin POST, PUT, PATCH, and DELETE should have a 400 and 404 response.
+            if route[:verb].in?([ "POST", "PUT", "PATCH", "DELETE" ]) && !extra_action
+              spec[:responses][400] = error_response
+              spec[:responses][404] = not_found_response
+            end
+
+            # All POST, PUT, PATCH should have a request body.
+            if route[:verb].in?([ "POST", "PUT", "PATCH" ])
+              spec[:requestBody] ||= { content: req_cts.map { |ct| [ ct, {} ] }.to_h }
+            end
+
+            # Add remaining metadata as an extension.
+            spec["x-rrf-metadata"] = metadata if metadata.present?
+
+            next route[:verb].downcase, spec
           }.to_h.merge(
             {
               parameters: routes.first[:route].required_parts.map { |p|
@@ -122,7 +127,7 @@ module RESTFramework::Mixins::BaseControllerMixin
                   name: p,
                   in: "path",
                   required: true,
-                  schema: {type: "integer"},
+                  schema: { type: "integer" },
                 }
               },
             },
@@ -134,16 +139,49 @@ module RESTFramework::Mixins::BaseControllerMixin
     def openapi_document(request, route_group_name, routes)
       server = request.base_url + request.original_fullpath.gsub(/\?.*/, "")
 
-      return {
+      {
         openapi: "3.1.1",
         info: {
           title: self.get_title,
           description: self.description,
           version: self.version.to_s,
         }.compact,
-        servers: [{url: server}],
+        servers: [ { url: server } ],
         paths: self.openapi_paths(routes, route_group_name),
-        tags: [{name: route_group_name, description: self.description}.compact],
+        tags: [ { name: route_group_name, description: self.description }.compact ],
+        components: {
+          schemas: {
+            "Error" => {
+              type: "object",
+              required: [ "message" ],
+              properties: {
+                message: { type: "string" },
+                errors: { type: "object" },
+                exception: { type: "string" },
+              },
+            },
+          },
+          responses: {
+            "BadRequest": {
+              description: "Bad Request",
+              content: self.openapi_response_content_types.map { |ct|
+                [
+                  ct,
+                  ct == "text/html" ? {} : { schema: { "$ref" => "#/components/schemas/Error" } },
+                ]
+              }.to_h,
+            },
+            "NotFound": {
+              description: "Not Found",
+              content: self.openapi_response_content_types.map { |ct|
+                [
+                  ct,
+                  ct == "text/html" ? {} : { schema: { "$ref" => "#/components/schemas/Error" } },
+                ]
+              }.to_h,
+            },
+          },
+        },
       }.compact
     end
   end
@@ -182,6 +220,7 @@ module RESTFramework::Mixins::BaseControllerMixin
       base.rescue_from(
         ActionController::ParameterMissing,
         ActionController::UnpermittedParameters,
+        ActionDispatch::Http::Parameters::ParseError,
         ActiveRecord::AssociationTypeMismatch,
         ActiveRecord::NotNullViolation,
         ActiveRecord::RecordNotFound,
@@ -195,7 +234,7 @@ module RESTFramework::Mixins::BaseControllerMixin
     end
 
     # Use `TracePoint` hook to automatically call `rrf_finalize`.
-    unless RESTFramework.config.disable_auto_finalize
+    if RESTFramework.config.auto_finalize
       # :nocov:
       TracePoint.trace(:end) do |t|
         next if base != t.self
@@ -211,12 +250,12 @@ module RESTFramework::Mixins::BaseControllerMixin
   end
 
   def get_serializer_class
-    return self.class.serializer_class
+    self.class.serializer_class
   end
 
   # Serialize the given data using the `serializer_class`.
   def serialize(data, **kwargs)
-    return RESTFramework::Utils.wrap_ams(self.get_serializer_class).new(
+    RESTFramework::Utils.wrap_ams(self.get_serializer_class).new(
       data, controller: self, **kwargs
     ).serialize
   end
@@ -229,8 +268,8 @@ module RESTFramework::Mixins::BaseControllerMixin
       400
     end
 
-    render_api(
-      {
+    render(
+      api: {
         message: e.message,
         errors: e.try(:record).try(:errors),
         exception: RESTFramework.config.show_backtrace ? e.full_message : nil,
@@ -240,7 +279,7 @@ module RESTFramework::Mixins::BaseControllerMixin
   end
 
   def route_groups
-    return @route_groups ||= RESTFramework::Utils.get_routes(Rails.application.routes, request)
+    @route_groups ||= RESTFramework::Utils.get_routes(Rails.application.routes, request)
   end
 
   # Render a browsable API for `html` format, along with basic `json`/`xml` formats, and with
@@ -341,11 +380,11 @@ module RESTFramework::Mixins::BaseControllerMixin
       end
     end
 
-    return document
+    document
   end
 
   def options
-    render_api(self.openapi_document)
+    render(api: self.openapi_document)
   end
 end
 

data/lib/rest_framework/mixins/bulk_model_controller_mixin.rb

@@ -7,17 +7,17 @@ module RESTFramework::Mixins::BulkCreateModelMixin
   # overloads the existing collection `POST` endpoint, so we add a special key to the OpenAPI
   # metadata to indicate bulk create is supported.
   def openapi_document
-    return super.merge({"x-rrf-bulk-create": true})
+    super.merge({ "x-rrf-bulk-create": true })
   end
 
   def create
     if params[:_json].is_a?(Array)
       records = self.create_all!
       serialized_records = self.bulk_serialize(records)
-      return render_api(serialized_records)
+      return render(api: serialized_records)
     end
 
-    return super
+    super
   end
 
   # Perform the `create` call, and return the collection of (possibly) created records.
@@ -25,9 +25,7 @@ module RESTFramework::Mixins::BulkCreateModelMixin
     create_data = self.get_create_params(bulk_mode: true)[:_json]
 
     # Perform bulk create in a transaction.
-    return ActiveRecord::Base.transaction do
-      next self.get_create_from.create(create_data)
-    end
+    ActiveRecord::Base.transaction { self.get_create_from.create(create_data) }
   end
 end
 
@@ -36,23 +34,21 @@ module RESTFramework::Mixins::BulkUpdateModelMixin
   def update_all
     records = self.update_all!
     serialized_records = self.bulk_serialize(records)
-    render_api(serialized_records)
+    render(api: serialized_records)
   end
 
   # Perform the `update` call and return the collection of (possibly) updated records.
   def update_all!
     pk = self.class.get_model.primary_key
-    update_data = if params[:_json].is_a?(Array)
+    data = if params[:_json].is_a?(Array)
       self.get_create_params(bulk_mode: :update)[:_json].index_by { |r| r[pk] }
     else
       create_params = self.get_create_params
-      {create_params[pk] => create_params}
+      { create_params[pk] => create_params }
     end
 
     # Perform bulk update in a transaction.
-    return ActiveRecord::Base.transaction do
-      next self.get_recordset.update(update_data.keys, update_data.values)
-    end
+    ActiveRecord::Base.transaction { self.get_recordset.update(data.keys, data.values) }
   end
 end
 
@@ -62,12 +58,11 @@ module RESTFramework::Mixins::BulkDestroyModelMixin
     if params[:_json].is_a?(Array)
       records = self.destroy_all!
       serialized_records = self.bulk_serialize(records)
-      return render_api(serialized_records)
+      return render(api: serialized_records)
     end
 
-    render_api(
-      {message: "Bulk destroy requires an array of primary keys as input."},
-      status: 400,
+    render(
+      api: { message: "Bulk destroy requires an array of primary keys as input." }, status: 400,
     )
   end
 
@@ -77,9 +72,7 @@ module RESTFramework::Mixins::BulkDestroyModelMixin
     destroy_data = self.request.request_parameters[:_json]
 
     # Perform bulk destroy in a transaction.
-    return ActiveRecord::Base.transaction do
-      next self.get_recordset.where(pk => destroy_data).destroy_all
-    end
+    ActiveRecord::Base.transaction { self.get_recordset.where(pk => destroy_data).destroy_all }
   end
 end