apia-open_api 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f046cce05d4154ba36e9f52227306129ef092e75061db7a522b44ade60b252c0
-  data.tar.gz: 2c56c6cedf8281819ca4c6382159183cdcc0c550d27375410f7f39cfe4bb842a
+  metadata.gz: 6621197f4a9535afae13e2a83de1fc5993290f379660e347afe989e94f3179ba
+  data.tar.gz: a932546d15d8302931a4c55d1fa4fa1e088b4f74ee7b227d0817de5f7b3f6dbb
 SHA512:
-  metadata.gz: 9c60e070b4a683379b689fff7c95ba8a7aa6ea9f2902e13b68474190b2aac234feec2428c73871591b467af2ba17be21c2dcb6d8b2297014a88e1ec783311472
-  data.tar.gz: afce3695675df681249591575c3704161caa3dd66b91a67e89bc67e58b07d45d8d6445e0080f7264c2a0fb234f1a03f87eec97aeeba22e39bf873f991b38452b
+  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 = 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,21 +134,26 @@ 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 nullable
+            schema[:properties][child.name.to_s][:nullable] = true
+          end
+
           if child.try(:required?)
             schema[:required] ||= []
             schema[:required] << child.name.to_s
@@ -137,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
-            schema[:properties][child.name.to_s] = generate_schema_ref(child)
+            ref = generate_schema_ref(child, sibling_props: nullable)
           else
             child_path = @path.nil? ? nil : @path + [child]
 
@@ -149,13 +173,16 @@ module Apia
             # very long IDs, so we truncate them to avoid hitting the 100 character
             # filename limit imposed by the rubygems gem builder.
             truncated_id = @id.match(/^(.*?)\d*?(Response|Part).*$/)[1]
-            schema[:properties][child.name.to_s] = generate_schema_ref(
+            ref = generate_schema_ref(
               child,
               id: "#{truncated_id}Part_#{child.name}".camelize,
+              sibling_props: nullable,
               endpoint: @endpoint,
               path: child_path
             )
           end
+
+          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.4"
+    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.4
+  version: 0.1.6
 platform: ruby
 authors:
 - Paul Sturgess
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-12-14 00:00:00.000000000 Z
+date: 2024-02-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -70,7 +70,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
+rubygems_version: 3.4.19
 signing_key: 
 specification_version: 4
 summary: Apia OpenAPI spec generator