apia-open_api 0.1.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7c3d54619c699cf9edca73ebc76e68819c2656f0259adbd6d5e411d4e415ca6
-  data.tar.gz: f31e758e511dd57af96896cd9ca956e6455c29747fc8389d5bda59a6c5938f3d
+  metadata.gz: 6621197f4a9535afae13e2a83de1fc5993290f379660e347afe989e94f3179ba
+  data.tar.gz: a932546d15d8302931a4c55d1fa4fa1e088b4f74ee7b227d0817de5f7b3f6dbb
 SHA512:
-  metadata.gz: 1f96b6eca24cc4d97d4e248892adf62bce141c4d4cce4697c8141cd1b844465d7ce9ef33036daddee81bf908dd41b4cc1bcad2b4436bc2cd1aef431e8fba8602
-  data.tar.gz: 1754bd390af23a0c88658c9a58b7c367f1743df4021a2f47c186720b3b3ff8235be743adaf62d0a3613502ae22267264f6aea71ae44ab716ba5ca8b86257345d
+  metadata.gz: d5bb084664b9a2729f8b0fb8408c8cd66eb6b8a637255582aba4c01cf5867eb2b88b5de5d1baba1eb4ebbece5f8d7353a7bedcbe68abe75036c7be9578a1a5c3
+  data.tar.gz: b99e2cc62ea871c657cbe523e1680d78f3341919b0a726d0fd6548635173a2064027c5c927d1a246be3120a508366e4627e4351c0040951d30a84694316fda3f

data/Gemfile

@@ -11,6 +11,7 @@ gem "rspec", "~> 3.0"
 gem "rubocop", "~> 1.21"
 
 group :test do
+  gem "openapi3_parser"
   gem "pry"
   gem "simplecov", require: false
 end

data/lib/apia/open_api/helpers.rb

@@ -52,17 +52,26 @@ module Apia
         schema
       end
 
-      def generate_schema_ref(definition, id: nil, **schema_opts)
+      def generate_schema_ref(definition, id: nil, sibling_props: false, **schema_opts)
         id ||= generate_id_from_definition(definition.type.klass.definition)
         success = add_to_components_schemas(definition, id, **schema_opts)
 
-        if success
+        # sibling_props indicates we want to allow sibling properties (typically setting nullable: true)
+        # In OpenAPI 3.0 sibling properties are not allowed for $refs (but are allowed in 3.1)
+        # Using allOf is a workaround to allow us to set a ref as `nullable` in OpenAPI 3.0
+        if success && sibling_props
+          {
+            allOf: [{ "$ref": "#/components/schemas/#{id}" }]
+          }
+        elsif success
           { "$ref": "#/components/schemas/#{id}" }
         else # no properties were defined, so just declare an object with unknown properties
           { type: "object" }
         end
       end
 
+      # Converts the definition id to a short version:
+      # e.g. CoreAPI/Objects/TimeZone => TimeZone
       def generate_id_from_definition(definition)
         definition.id.split("/").last
       end

data/lib/apia/open_api/objects/response.rb

@@ -98,15 +98,15 @@ module Apia
           else
             # We assume the partially selected attributes must be present in all of the polymorph options
             # and that each option returns the same data type for that attribute.
-            # The same 'allOf workaround' is used here as for objects and enums below.
             ref = generate_schema_ref(
               field.type.klass.definition.options.values.first,
               id: generate_field_id(field_name),
+              sibling_props: field.description.present? || field.null?,
               endpoint: @endpoint,
               path: [field]
             )
 
-            properties[field_name] = { allOf: [ref] }
+            properties[field_name] = ref
           end
           properties[field_name][:description] = field.description if field.description.present?
         end
@@ -135,28 +135,32 @@ module Apia
           properties[field_name][:description] = field.description if field.description.present?
         end
 
-        # Using allOf is a 'workaround' so that we can include a description for the field
-        # In OpenAPI 3.0 sibling properties are not allowed for $refs (but are allowed in 3.1)
         # We don't want to put the description on the $ref itself because the description is
         # specific to the endpoint and not necessarily applicable to all uses of the $ref.
         def build_properties_for_object_or_enum(field_name, field, properties)
-          properties[field_name] = {}
-          properties[field_name][:description] = field.description if field.description.present?
+          sibling_props = field.description.present? || field.null?
           if field_includes_all_properties?(field)
-            ref = generate_schema_ref(field)
+            ref = generate_schema_ref(field, sibling_props: sibling_props)
           else
             ref = generate_schema_ref(
               field,
               id: generate_field_id(field_name),
+              sibling_props: sibling_props,
               endpoint: @endpoint,
               path: [field]
             )
           end
-          properties[field_name][:allOf] = [ref]
+
+          properties[field_name] = {
+            description: (field.description if field.description.present?),
+            **ref
+          }.compact
         end
 
+        # We used to check if field.include was nil, but explicitly checking for a string is more robust.
+        # As some apia definitions declare `include: true`, which is not the correct way to use the option.
         def field_includes_all_properties?(field)
-          field.include.nil?
+          !field.include.is_a?(String)
         end
 
         def generate_field_id(field_name)
@@ -173,7 +177,11 @@ module Apia
             d.http_status_code.to_s.to_sym
           end
 
-          sorted_grouped_potential_errors = grouped_potential_errors.sort_by do |http_status_code, _|
+          deduplicated_potential_errors = grouped_potential_errors.map do |http_status_code, potential_errors|
+            [http_status_code, potential_errors.uniq { |error| error.code }]
+          end
+
+          sorted_grouped_potential_errors = deduplicated_potential_errors.sort_by do |http_status_code, _|
             http_status_code.to_s.to_i
           end
 
@@ -270,6 +278,7 @@ module Apia
               oneOf: definitions.map { |d| generate_ref("schemas", http_status_code, [d]) }
             }
 
+            # we don't need the ref allOf workaround here because these responses are not nullable
             schema = { "$ref": "#/components/schemas/#{one_of_id}" }
           end
 

data/lib/apia/open_api/objects/schema.rb

@@ -40,7 +40,7 @@ module Apia
           @definition = definition
           @schema = schema
           @id = id
-          @endpoint = endpoint # endpoint gets specified when we are dealing with a partial response
+          @endpoint = endpoint # endpoint gets specified when we are dealing with a partial response (see below)
           @path = path
           @children = []
         end
@@ -90,10 +90,10 @@ module Apia
 
           return if @children.empty?
 
-          all_properties_included = error_definition? || enum_definition? || @endpoint.nil?
           @children.each do |child|
             next unless @endpoint.nil? || (!enum_definition? && @endpoint.include_field?(@path + [child]))
 
+            all_properties_included = all_properties_included_for_child?(child)
             if child.respond_to?(:array?) && child.array?
               generate_schema_for_child_array(@schema, child, all_properties_included)
             else
@@ -102,6 +102,25 @@ module Apia
           end
         end
 
+        # We need to check if all properties are included, because if they aren't we cannot use
+        # an existing schema $ref. We need to generate a new schema only for the endpoint.
+        # A field is considered 'partial' when declared in Apia with the `include` option, e.g.:
+        # ```
+        #   field :zones,
+        #     type: [Objects::Zone],
+        #     include: 'id,name,permalink,data_center[reference]'
+        # ```
+        # the above example means we only want to include the id, name and permalink fields for the zone
+        # and data_center is a nested object in zone, which should only include reference.
+        # so the parent zone is a partial object and the child data_center is also a partial object.
+        def all_properties_included_for_child?(child)
+          return true if error_definition? || enum_definition? || @endpoint.nil? || !child.type.object?
+
+          child.type.klass.definition.fields.values.all? do |child_field|
+            @endpoint.include_field?(@path + [child, child_field])
+          end
+        end
+
         def generate_schema_for_child_array(schema, child, all_properties_included)
           child_schema = generate_schema_for_child({}, child, all_properties_included)
           items = child_schema.dig(:properties, child.name.to_s)
@@ -115,22 +134,23 @@ module Apia
         end
 
         def generate_schema_for_child(schema, child, all_properties_included)
+          nullable = child.try(:null?)
           if enum_definition?
             schema[:type] = "string"
             schema[:enum] = @children.map { |c| c[:name] }
           elsif child.type.argument_set? || child.type.enum? || child.type.polymorph?
             schema[:type] = "object"
             schema[:properties] ||= {}
-            schema[:properties][child.name.to_s] = generate_schema_ref(child)
+            schema[:properties][child.name.to_s] = generate_schema_ref(child, sibling_props: nullable)
           elsif child.type.object?
-            generate_properties_for_object(schema, child, all_properties_included)
+            generate_properties_for_object(schema, child, all_properties_included, nullable)
           else # scalar
             schema[:type] = "object"
             schema[:properties] ||= {}
             schema[:properties][child.name.to_s] = generate_scalar_schema(child)
           end
 
-          if child.try(:null?)
+          if nullable
             schema[:properties][child.name.to_s][:nullable] = true
           end
 
@@ -141,11 +161,11 @@ module Apia
           schema
         end
 
-        def generate_properties_for_object(schema, child, all_properties_included)
+        def generate_properties_for_object(schema, child, all_properties_included, nullable)
           schema[:type] = "object"
           schema[:properties] ||= {}
           if all_properties_included
-            ref = generate_schema_ref(child)
+            ref = generate_schema_ref(child, sibling_props: nullable)
           else
             child_path = @path.nil? ? nil : @path + [child]
 
@@ -156,13 +176,13 @@ module Apia
             ref = generate_schema_ref(
               child,
               id: "#{truncated_id}Part_#{child.name}".camelize,
+              sibling_props: nullable,
               endpoint: @endpoint,
               path: child_path
             )
           end
 
-          # Using allOf is a workaround to allow us to set a ref as `nullable` in OpenAPI 3.0
-          schema[:properties][child.name.to_s] = { allOf: [ref] }
+          schema[:properties][child.name.to_s] = ref
         end
 
       end

data/lib/apia/open_api/specification.rb

@@ -28,6 +28,9 @@ module Apia
           },
           security: []
         }
+
+        # path_ids is used to keep track of all the IDs of all the paths we've generated, to avoid duplicates
+        # refer to the Path object for more info
         @path_ids = []
         build_spec
       end
@@ -60,7 +63,9 @@ module Apia
 
       def add_paths
         @api.definition.route_set.routes.each do |route|
-          next unless route.endpoint.definition.schema? # not all routes should be documented
+          # not all routes should be documented
+          next unless route.group.nil? || route.group.schema?
+          next unless route.endpoint.definition.schema?
 
           Objects::Path.new(
             spec: @spec,

data/lib/apia/open_api/version.rb

@@ -3,7 +3,7 @@
 module Apia
   module OpenApi
 
-    VERSION = "0.1.5"
+    VERSION = "0.1.6"
 
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: apia-open_api
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.6
 platform: ruby
 authors:
 - Paul Sturgess
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-01-24 00:00:00.000000000 Z
+date: 2024-02-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport