apia-open_api 0.1.5 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7c3d54619c699cf9edca73ebc76e68819c2656f0259adbd6d5e411d4e415ca6
-  data.tar.gz: f31e758e511dd57af96896cd9ca956e6455c29747fc8389d5bda59a6c5938f3d
+  metadata.gz: ce32b2c3d98cff03c533669e56c860dcda6b97a0deb554d423f8c208645ea87a
+  data.tar.gz: 9f9d5b952f2cc7141a0c207fa8d43c9d5d7a2a617dabb1819bb07e6a7decc691
 SHA512:
-  metadata.gz: 1f96b6eca24cc4d97d4e248892adf62bce141c4d4cce4697c8141cd1b844465d7ce9ef33036daddee81bf908dd41b4cc1bcad2b4436bc2cd1aef431e8fba8602
-  data.tar.gz: 1754bd390af23a0c88658c9a58b7c367f1743df4021a2f47c186720b3b3ff8235be743adaf62d0a3613502ae22267264f6aea71ae44ab716ba5ca8b86257345d
+  metadata.gz: 5b83929f1bc986f6ce7d8d736f30b76992868bd6442d72b9f8456d83537bc91b1b8d4297ad94655aaf86720d40468305215f2e28fcd61f63253ee9d24fc59874
+  data.tar.gz: 13c108fcb4596a5912781732192e4bac034c6dd7a441e951edff6b740515e188a3ee03ba73cb63c518f235bff5a57b09a0dd3a8f3dcff77f79ccfb81edfbb61c

data/Gemfile

@@ -5,12 +5,13 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in apia-open_api.gemspec
 gemspec
 
-gem "apia", "~> 3.5"
+gem "apia", "~> 3.7"
 gem "rake", "~> 13.0"
 gem "rspec", "~> 3.0"
 gem "rubocop", "~> 1.21"
 
 group :test do
+  gem "openapi3_parser"
   gem "pry"
   gem "simplecov", require: false
 end

data/README.md

@@ -1,6 +1,6 @@
 # Apia OpenAPI Specification
 
-This gem can generate an [OpenAPI](https://www.openapis.org/) compatible schema from an API implemented using [Apia](https://github.com/krystal/apia).
+This gem can generate an [OpenAPI](https://www.openapis.org/) compatible schema from an API implemented using [Apia](https://github.com/apiaframework/apia).
 
 This gem is in the early phases of development and breaking changes may be introduced whilst the gem is in the 0.1.x version range.
 
@@ -12,7 +12,7 @@ Install the gem and add to the application's Gemfile by executing:
 
 ## Usage
 
-The schema can be mounted in much the same way as an [Apia API](https://github.com/krystal/apia) itself.
+The schema can be mounted in much the same way as an [Apia API](https://github.com/apiaframework/apia) itself.
 
 For example, for a Ruby on Rails application:
 
@@ -85,7 +85,7 @@ You can also run `bin/console` for an interactive prompt that will allow you to
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/krystal/apia-open_api.
+Bug reports and pull requests are welcome on GitHub at https://github.com/apiaframework/apia-open_api.
 
 ## License
 

data/apia-open_api.gemspec

@@ -8,13 +8,13 @@ Gem::Specification.new do |spec|
   spec.authors = ["Paul Sturgess"]
 
   spec.summary = "Apia OpenAPI spec generator"
-  spec.homepage = "https://github.com/krystal/apia-openapi"
+  spec.homepage = "https://github.com/apiaframework/apia-openapi"
   spec.license = "MIT"
   spec.required_ruby_version = ">= 2.7.0"
 
   spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "https://github.com/krystal/apia-openapi"
-  spec.metadata["changelog_uri"] = "https://github.com/krystal/apia-openapi/changelog.md"
+  spec.metadata["source_code_uri"] = "https://github.com/apiaframework/apia-openapi"
+  spec.metadata["changelog_uri"] = "https://github.com/apiaframework/apia-openapi/changelog.md"
 
   spec.metadata["rubygems_mfa_required"] = "false" # rubocop:disable Gemspec/RequireMFA (enabling MFA means we cannot auto publish via the CI)
 

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

@@ -36,6 +36,7 @@ module Apia
           @route_spec = route_spec
           @api_authenticator = api_authenticator
           @http_status = @endpoint.definition.http_status
+          @response_type = @endpoint.definition.response_type
         end
 
         def add_to_spec
@@ -46,9 +47,14 @@ module Apia
         private
 
         def add_sucessful_response_schema
-          content_schema = {
-            properties: generate_properties_for_successful_response
-          }
+          if @response_type == Apia::Response::PLAIN
+            content_schema = { type: "string" }
+          else
+            content_schema = {
+              properties: generate_properties_for_successful_response
+            }
+          end
+
           required_fields = @endpoint.definition.fields.select { |_, field| field.condition.nil? }
           content_schema[:required] = required_fields.keys if required_fields.any?
 
@@ -56,7 +62,7 @@ module Apia
             "#{@http_status}": {
               description: @endpoint.definition.description || "",
               content: {
-                "application/json": {
+                @response_type => {
                   schema: content_schema
                 }
               }
@@ -98,15 +104,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 +141,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 +183,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 +284,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.7"
 
   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.7
 platform: ruby
 authors:
 - Paul Sturgess
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-01-24 00:00:00.000000000 Z
+date: 2024-05-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -47,13 +47,13 @@ files:
 - lib/apia/open_api/rack.rb
 - lib/apia/open_api/specification.rb
 - lib/apia/open_api/version.rb
-homepage: https://github.com/krystal/apia-openapi
+homepage: https://github.com/apiaframework/apia-openapi
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/krystal/apia-openapi
-  source_code_uri: https://github.com/krystal/apia-openapi
-  changelog_uri: https://github.com/krystal/apia-openapi/changelog.md
+  homepage_uri: https://github.com/apiaframework/apia-openapi
+  source_code_uri: https://github.com/apiaframework/apia-openapi
+  changelog_uri: https://github.com/apiaframework/apia-openapi/changelog.md
   rubygems_mfa_required: 'false'
 post_install_message: 
 rdoc_options: []