apia-open_api 0.1.9 → 0.1.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab4263122239dfce8e477f4279cbe4a03743f0e6fa4c1236c0480082d517ec8c
-  data.tar.gz: 8542223956ac7fc5fc4817cc627c0d5ec96876cd1f671a4e26422deae3818387
+  metadata.gz: 9105b1350ceecf58bdf2037f3052a50f38ec76be818c67016c46381a68fb2f4b
+  data.tar.gz: 433da5d349c9aabd1f71277e5b41885b8bcc514cda52ca0f8c659470307c01c7
 SHA512:
-  metadata.gz: 05131ea1ca348bce2d637314eba336e07bb4553f71ef3fd107c23ee854f107f09b26d24c0cdfdebb259ef450421bbcdc8864b6ac8fc057e32ac8570d590f24eb
-  data.tar.gz: 95cad90b7979f85e4cc085bb25ea7f33583766f8b05ef94a8ac91a93701e27e6b757bc3e63141211a9fab5dad16f57872b98dd3ad1c5a77fefa4c25c9b4f3bb1
+  metadata.gz: a6bc4e0c62791abe13bcc5742270e0faefc30cbed76a140a1fed6afa766dd3635f344fbb3b322a7f5f1fec02c2c4d69cc90ec0866a661a971e619fe76662a543
+  data.tar.gz: dbb0d647cea2e6f208fee6426dd5b7bbb3270a8bcbbdbb7a84ca2bc9a1975cecfe98caa7a729e859357493085a1639e9b8c2be24662b96c3c4cf69e238fed0ca

data/lib/apia/open_api/helpers.rb

@@ -52,6 +52,20 @@ module Apia
         schema
       end
 
+      def generate_array_schema(definition)
+        type = definition.type
+        schema = {
+          type: "array",
+          items: {
+            type: convert_type_to_open_api_data_type(type)
+          }
+        }
+        schema[:description] = definition.description if definition.description.present?
+        schema[:items][:format] = "float" if type.klass == Apia::Scalars::Decimal
+        schema[:items][:format] = "date" if type.klass == Apia::Scalars::Date
+        schema
+      end
+
       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)

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

@@ -69,6 +69,9 @@ module Apia
               schema: generate_scalar_schema(@argument)
             }
             param[:description] = @argument.description if @argument.description.present?
+
+            add_pagination_params(param)
+
             param[:required] = true if @argument.required?
             add_to_parameters(param)
           end
@@ -76,6 +79,19 @@ module Apia
 
         private
 
+        def add_pagination_params(param)
+          if param[:name] == "page"
+            param[:description] = "The page number to request. If not provided, the first page will be returned."
+            param[:schema][:default] = 1
+            param[:schema][:minimum] = 1
+          elsif param[:name] == "per_page"
+            param[:description] =
+              "The number of items to return per page. If not provided, the default value will be used."
+            param[:schema][:default] = @argument.default
+            param[:schema][:minimum] = 1
+          end
+        end
+
         # Complex argument sets are not supported in query params (e.g. nested objects)
         # For any LookupArgumentSet only one argument is expected to be provided.
         # However, OpenAPI does not currently support describing mutually exclusive query params.
@@ -87,19 +103,55 @@ module Apia
             next if child_arg.type.argument_set?
 
             param = {
-              name: "#{@argument.name}[#{child_arg.name}]",
-              in: "query",
-              schema: generate_scalar_schema(child_arg)
+              in: "query"
             }
+
             description = []
             description << formatted_description(@argument.description) if @argument.description.present?
             description << formatted_description(child_arg.description) if child_arg.description.present?
-            description << "All '#{@argument.name}[]' params are mutually exclusive, only one can be provided."
+
+            add_lookup_description(description)
+
+            if @argument.array
+              param[:name] = "#{@argument.name}[][#{child_arg.name}]"
+              param[:schema] = generate_array_schema(child_arg)
+
+              add_description_section(
+                description,
+                "All `#{@argument.name}[]` params should have the same amount of elements."
+              )
+
+            else
+              param[:name] = "#{@argument.name}[#{child_arg.name}]"
+              param[:schema] = generate_scalar_schema(child_arg)
+            end
+
             param[:description] = description.join(" ")
             add_to_parameters(param)
           end
         end
 
+        # Adds a section to the description of a parameter.
+        # If the description is not empty, a blank line is added before the section.
+        #
+        # @param description [String] The current description of the parameter.
+        # @param addition [String] The section to be added to the description.
+        # @return [String] The updated description with the added section.
+        def add_description_section(description, addition)
+          unless description.empty?
+            description << "\n\n"
+          end
+
+          description << addition
+        end
+
+        def add_lookup_description(description)
+          add_description_section(
+            description,
+            "All '#{@argument.name}[]' params are mutually exclusive, only one can be provided."
+          )
+        end
+
         def add_to_parameters(param)
           @route_spec[:parameters] << param
         end

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

@@ -38,12 +38,14 @@ module Apia
             operationId: convert_route_to_id,
             summary: @route.endpoint.definition.name,
             description: @route.endpoint.definition.description,
-            tags: route.group ? get_group_tags(route.group) : [name]
+            tags: route.group ? get_group_tags(route.group) : [name],
+            security: []
           }
         end
 
         def add_to_spec
           add_scopes_description
+          add_scopes_security
           path = @route.path
 
           if @route.request_method == :get
@@ -104,6 +106,45 @@ module Apia
                 "- `#{scope}`"
               end.join("\n")}
             DESCRIPTION
+
+          @spec[:security].each do |auth|
+            auth.each_key do |key|
+              scope_prefix = @spec[:components][:securitySchemes][key][:"x-scope-prefix"]
+              next unless scope_prefix.present?
+
+              @route_spec[:description] =
+                <<~DESCRIPTION
+                  #{@route_spec[:description]}
+                  ### #{key} Scopes
+                  When using #{key} authentication, scopes are prefixed with `#{scope_prefix}`.
+                DESCRIPTION
+            end
+          end
+        end
+
+        # Adds scopes security to the OpenAPI path specification.
+        #
+        # This method checks if the route's endpoint definition has any scopes defined.
+        # If scopes are present, it iterates over the security schemes in the OpenAPI
+        # specification and adds the corresponding scopes to the route's security section.
+        #
+        # @return [void]
+        def add_scopes_security
+          unless @route.endpoint.definition.scopes.any?
+            @route_spec.delete(:security)
+            return
+          end
+
+          @spec[:security].each do |auth|
+            auth.each_key do |key|
+              scopes = @route.endpoint.definition.scopes
+              if scope_prefix = @spec[:components][:securitySchemes][key][:"x-scope-prefix"]
+                scopes = scopes.map { |v| "#{scope_prefix}/#{v}" }
+              end
+
+              @route_spec[:security] << { key => scopes }
+            end
+          end
         end
 
         # It's worth creating a 'nice' operationId for each route, as this is used as the
@@ -162,6 +203,15 @@ module Apia
           current_group = group
 
           while current_group
+            # Add tags to the spec global tags if they don't already exist
+            # Include a description if the group has one.
+            unless @spec[:tags].any? { |t| t[:name] == current_group.name }
+              global_tag = { name: current_group.name }
+              global_tag[:description] = current_group.description if current_group.description
+              @spec[:tags] << global_tag
+
+            end
+
             tags.unshift(current_group.name)
             current_group = current_group.parent
           end

data/lib/apia/open_api/rack.rb

@@ -29,6 +29,18 @@ module Apia
         @options[:base_url] || "https://api.example.com/api/v1"
       end
 
+      def security_schemes
+        @options[:security_schemes] || {}
+      end
+
+      def external_docs
+        @options[:external_docs] || {}
+      end
+
+      def info
+        @options[:info] || {}
+      end
+
       def call(env)
         if @options[:hosts]&.none? { |host| host == env["HTTP_HOST"] }
           return @app.call(env)
@@ -38,7 +50,12 @@ module Apia
           return @app.call(env)
         end
 
-        specification = Specification.new(api_class, base_url, @options[:name])
+        specification = Specification.new(api_class, base_url, @options[:name],
+                                          {
+                                              info: info,
+                                              external_docs: external_docs,
+                                              security_schemes: security_schemes
+                                          })
         body = specification.json
 
         [200, { "content-type" => "application/json", "content-length" => body.bytesize.to_s }, [body]]

data/lib/apia/open_api/specification.rb

@@ -14,13 +14,17 @@ module Apia
 
       OPEN_API_VERSION = "3.0.0" # The Ruby client generator currently only supports v3.0.0 https://openapi-generator.tech/
 
-      def initialize(api, base_url, name)
+      def initialize(api, base_url, name, additions = {})
+        default_additions = { info: {}, external_docs: {}, security_schemes: {} }
+        additions = default_additions.merge(additions)
+
         @api = api
         @base_url = base_url
         @name = name || "Core" # will be suffixed with 'Api' and used in the client generator
         @spec = {
           openapi: OPEN_API_VERSION,
-          info: {},
+          info: additions[:info],
+          externalDocs: additions[:external_docs],
           servers: [],
           paths: {},
           components: {
@@ -31,6 +35,12 @@ module Apia
           "x-tagGroups": []
         }
 
+        if @spec[:externalDocs].nil? || @spec[:externalDocs].empty?
+          @spec.delete(:externalDocs)
+        end
+
+        add_additional_security_schemes(additions[:security_schemes])
+
         # 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 = []
@@ -52,8 +62,8 @@ module Apia
       def build_spec
         add_info
         add_servers
-        add_paths
         add_security
+        add_paths
         add_tag_groups
 
         @spec[:paths] = sort_hash_by_nested_tag(@spec[:paths])
@@ -61,11 +71,13 @@ module Apia
 
       def add_info
         title = @api.definition.name || @api.definition.id
-        @spec[:info] = {
-          version: "1.0.0",
-          title: title
-        }
-        @spec[:info][:description] = @api.definition.description || "Welcome to the documentation for the #{title}"
+        @spec[:info][:version] = "1.0.0" if @spec[:info][:version].nil?
+        @spec[:info][:title] = title if @spec[:info][:title].nil?
+
+        return unless @spec[:info][:description].nil?
+
+        @spec[:info][:description] =
+          @api.definition.description || "Welcome to the documentation for the #{title}"
       end
 
       def add_servers
@@ -119,15 +131,11 @@ module Apia
       def add_tag_groups
         @spec[:paths].each_value do |methods|
           methods.each_value do |method_spec|
-            method_spec[:tags].each_with_index do |tag, tag_index|
-              unless @spec[:tags].any? { |t| t[:name] == tag }
-                @spec[:tags] << { name: tag }
-              end
+            tags = method_spec[:tags]
 
+            tags.each_with_index do |tag, tag_index|
               next if tag_index.zero?
 
-              tags = method_spec[:tags]
-
               parent_tag = tags[tag_index - 1]
               parent_index = get_tag_group_index(parent_tag)
 
@@ -140,6 +148,10 @@ module Apia
                 @spec[:"x-tagGroups"][parent_index][:tags] << tag
               end
             end
+
+            # Set the last tag as the tag for the method
+            # After we have built the tag group.
+            method_spec[:tags] = [tags.last] if tags.any?
           end
         end
 
@@ -153,6 +165,14 @@ module Apia
         @spec[:"x-tagGroups"].each { |group| group[:tags].sort! }
       end
 
+      def add_additional_security_schemes(security_schemes)
+        security_schemes.each do |key, value|
+          @spec[:components][:securitySchemes] ||= {}
+          @spec[:components][:securitySchemes][key] = value.transform_keys(&:to_sym)
+          @spec[:security] << { key => [] }
+        end
+      end
+
     end
   end
 end

data/lib/apia/open_api/version.rb

@@ -3,7 +3,7 @@
 module Apia
   module OpenApi
 
-    VERSION = "0.1.9"
+    VERSION = "0.1.11"
 
   end
 end

metadata

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