apia-open_api 0.1.8 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 18cbf0db6400c3d1e60a769d2064e77259bc3368ccf39e8c8b4d8c3ae99125b9
-  data.tar.gz: c29814927fee005a855592a8d7c7689decfffdb534c5cae5d7c1d4ec1a367d54
+  metadata.gz: ab4263122239dfce8e477f4279cbe4a03743f0e6fa4c1236c0480082d517ec8c
+  data.tar.gz: 8542223956ac7fc5fc4817cc627c0d5ec96876cd1f671a4e26422deae3818387
 SHA512:
-  metadata.gz: fe2929de95c1b355815cb0d18a91af8fa373cd948ebf0465067211f75b9a3c5dc4f46795572b8ff5ce136410d0ae7865e01d8ea9c5a497adad272cb1f2e7f020
-  data.tar.gz: bfd2cd9fe9a6a2e4148c9bf95b86b698584913c791fe03def05f99d56e484c1a49551e65fdac656d95229a90fbc6a24f41f19261d0e06f406bb7adb18bef2613
+  metadata.gz: 05131ea1ca348bce2d637314eba336e07bb4553f71ef3fd107c23ee854f107f09b26d24c0cdfdebb259ef450421bbcdc8864b6ac8fc057e32ac8570d590f24eb
+  data.tar.gz: 95cad90b7979f85e4cc085bb25ea7f33583766f8b05ef94a8ac91a93701e27e6b757bc3e63141211a9fab5dad16f57872b98dd3ad1c5a77fefa4c25c9b4f3bb1

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

@@ -36,20 +36,29 @@ 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]
           }
         end
 
         def add_to_spec
+          add_scopes_description
           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 +88,24 @@ 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
+        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 +153,22 @@ 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
+            tags.unshift(current_group.name)
+            current_group = current_group.parent
+          end
+
+          tags
+        end
+
       end
     end
   end

data/lib/apia/open_api/rack.rb

@@ -41,7 +41,7 @@ module Apia
         specification = Specification.new(api_class, base_url, @options[:name])
         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

@@ -26,7 +26,9 @@ module Apia
           components: {
             schemas: {}
           },
-          security: []
+          security: [],
+          tags: [],
+          "x-tagGroups": []
         }
 
         # path_ids is used to keep track of all the IDs of all the paths we've generated, to avoid duplicates
@@ -41,11 +43,20 @@ 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_tag_groups
+
+        @spec[:paths] = sort_hash_by_nested_tag(@spec[:paths])
       end
 
       def add_info
@@ -85,6 +96,63 @@ 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|
+            method_spec[:tags].each_with_index do |tag, tag_index|
+              unless @spec[:tags].any? { |t| t[:name] == tag }
+                @spec[:tags] << { name: tag }
+              end
+
+              next if tag_index.zero?
+
+              tags = method_spec[:tags]
+
+              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
+          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
+
     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.9"
 
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: apia-open_api
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.1.9
 platform: ruby
 authors:
 - Paul Sturgess