apia-open_api 0.1.8 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 18cbf0db6400c3d1e60a769d2064e77259bc3368ccf39e8c8b4d8c3ae99125b9
-  data.tar.gz: c29814927fee005a855592a8d7c7689decfffdb534c5cae5d7c1d4ec1a367d54
+  metadata.gz: 2018fe92f478024edd0b15086e2844c6f540cecccdc508d246c2ee9f705dde8d
+  data.tar.gz: 0dda2bc96afb05c930a42e89d50c66bfdc38630345be9772cd06244e94cb3574
 SHA512:
-  metadata.gz: fe2929de95c1b355815cb0d18a91af8fa373cd948ebf0465067211f75b9a3c5dc4f46795572b8ff5ce136410d0ae7865e01d8ea9c5a497adad272cb1f2e7f020
-  data.tar.gz: bfd2cd9fe9a6a2e4148c9bf95b86b698584913c791fe03def05f99d56e484c1a49551e65fdac656d95229a90fbc6a24f41f19261d0e06f406bb7adb18bef2613
+  metadata.gz: 19ff009aa99228b72250b56c354a191a2407fe5f4abde636de07d637e7ed4bc4ddd6ae419d38234f8e1fdf58c073895379144d97ce2030aab440ccc8a2f0c21e
+  data.tar.gz: 9b739acb6d8ced837e49a5e25e46956ed2847143e3a60c0cd8fb46acbe79d6b5c2b25f64e5c9e2ba5db656f076f7add0c7e54c114e51b4b0a6d41dfcf270fec3

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

@@ -36,20 +36,31 @@ module Apia
           @api_authenticator = api_authenticator
           @route_spec = {
             operationId: convert_route_to_id,
-            tags: [name]
+            summary: @route.endpoint.definition.name,
+            description: @route.endpoint.definition.description,
+            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
             add_parameters
           else
             add_request_body
           end
 
-          @spec[:paths]["/#{path}"] ||= {}
-          @spec[:paths]["/#{path}"][@route.request_method.to_s] = @route_spec
+          path = "/#{path}"
+          # Remove the `:` from the url parameters in the path
+          # This is because some tools based on the OpenAPI spec don't like the `:` in the path
+          path = path.gsub(/:([^\/]+)/, '\1')
+
+          @spec[:paths][path] ||= {}
+          @spec[:paths][path][@route.request_method.to_s] = @route_spec
 
           add_responses
         end
@@ -79,6 +90,63 @@ module Apia
           ).add_to_spec
         end
 
+        # Adds a description of the scopes to the route specification.
+        #
+        # This method checks if the route's endpoint definition has any scopes.
+        # If there are scopes, it appends a description of the scopes to the existing route specification description.
+        # The description of the scopes is formatted as a markdown list, with each scope represented as a bullet point.
+        def add_scopes_description
+          return unless @route.endpoint.definition.scopes.any?
+
+          @route_spec[:description] =
+            <<~DESCRIPTION
+              #{@route_spec[:description]}
+              ## Scopes
+              #{@route.endpoint.definition.scopes.map do |scope|
+                "- `#{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
         # basis for the method name when calling the endpoint using a generated client.
         def convert_route_to_id
@@ -126,6 +194,31 @@ module Apia
           "#{first_part}#{last_part}"
         end
 
+        # Returns an array of tags representing the group hierarchy for a given group.
+        #
+        # @param group [Group] The group for which to retrieve the tags.
+        # @return [Array<String>] An array of tags representing the group hierarchy.
+        def get_group_tags(group)
+          tags = []
+          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
+
+          tags
+        end
+
       end
     end
   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,10 +50,15 @@ 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]]
+        [200, { "content-type" => "application/json", "content-length" => body.bytesize.to_s }, [body]]
       end
 
     end

data/lib/apia/open_api/specification.rb

@@ -14,21 +14,33 @@ 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: {
             schemas: {}
           },
-          security: []
+          security: [],
+          tags: [],
+          "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 = []
@@ -41,20 +53,31 @@ module Apia
 
       private
 
+      def sort_hash_by_nested_tag(hash)
+        hash.sort_by do |_, nested_hash|
+          nested_hash.values.first[:tags]&.first
+        end.to_h
+      end
+
       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])
       end
 
       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
@@ -85,6 +108,71 @@ module Apia
         end
       end
 
+      def get_tag_group_index(tag)
+        @spec[:"x-tagGroups"].each_with_index do |group, index|
+          return index if !group.nil? && group[:name] == tag
+        end
+
+        nil
+      end
+
+      # Adds tag groups to the OpenAPI specification.
+      #
+      # This method iterates over the paths in the specification and adds tag groups
+      # based on the tags specified for each method.
+      # It ensures that each tag is included in the `tags` array of the specification,
+      # and creates tag groups based on the order of the tags.
+      # Tag groups are represented by the `x-tagGroups` property in the specification.
+      # Tag groups are nested groups and are used to group tags together in documentation.
+      # A Tag *must* be included in a tag group. So if it is not part of a group / has no parent tag,
+      # it will be added to a group with the same name as the tag.
+      #
+      # @return [void]
+      def add_tag_groups
+        @spec[:paths].each_value do |methods|
+          methods.each_value do |method_spec|
+            tags = method_spec[:tags]
+
+            tags.each_with_index do |tag, tag_index|
+              next if tag_index.zero?
+
+              parent_tag = tags[tag_index - 1]
+              parent_index = get_tag_group_index(parent_tag)
+
+              if parent_index.nil? && tags.size > 1
+                @spec[:"x-tagGroups"] << { name: parent_tag, tags: [parent_tag] }
+                parent_index = @spec[:"x-tagGroups"].size - 1
+              end
+
+              unless @spec[:"x-tagGroups"][parent_index][:tags].include?(tag)
+                @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
+
+        @spec[:tags].each do |tag|
+          unless @spec[:"x-tagGroups"].any? { |group| group[:tags].include?(tag[:name]) }
+            @spec[:"x-tagGroups"] << { name: tag[:name], tags: [tag[:name]] }
+          end
+        end
+
+        @spec[:"x-tagGroups"].sort_by! { |group| group[:name] }
+        @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
+          @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.8"
+    VERSION = "0.1.10"
 
   end
 end

metadata

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