gitlab-grape-openapi 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b864030f21b5380efa37ccb02b953f5c8d07b2f4d2fe90eb66334e155674e2bc
-  data.tar.gz: 37b0f04c277c0b1f1027bdb5f0839f06641a3c6e11fd2e9498cb9a192899914b
+  metadata.gz: 1a821f273e073b35414be3f6c2c7f34e517288e2adb77c7eb55c3076b095b464
+  data.tar.gz: 46cdf4d7cbef2541b3b5b4a56402dfb96d1f9d3740a6fcba9122d6b32b7112cf
 SHA512:
-  metadata.gz: d7e270e89449c2f1dbdfa2f6acb4bb841abf7bbb25adf064a3f41fbf2a61eb8e9f86f698d8c826cdb111cf19aa6f21269984453913fc53554ce6f7f8eb502ba8
-  data.tar.gz: a6e772a0f79d6d1e010ddddf7a6504a96da9d94c2ad34db08bbf58d80e7bffd8df0364dc09b361c0da5cce3d2b163a2dc24cb5d57604a543926a2c1ddc4ed5fa
+  metadata.gz: 6bf28a6d866c98071dca44a278e52b575c66481a9acefae7c658a9206a8d678f992777bd682b0782fd30f7206de634a2f58f7f5fea45bdc2d72039cba1263422
+  data.tar.gz: bcf139d99fcefaeb2a51af83251b431ba5b7bad9eac4df549f7e160e418144dbc6f06dbf4fbe8285c1fa0acd058dbcb1b7d510180cc589d80c71a276bbea59c1

data/README.md

@@ -30,11 +30,13 @@ Internal gem for generating [OpenAPI 3.0](https://spec.openapis.org/oas/v3.0.0)
   - [Parameter constraints](#parameter-constraints)
   - [Registries](#registries)
   - [Response media types](#response-media-types)
+  - [Schema-file responses](#schema-file-responses)
   - [Optional path segments](#optional-path-segments)
   - [Operation IDs and request body schemas](#operation-ids-and-request-body-schemas)
 - [Development](#development)
   - [Running Tests](#running-tests)
   - [Linting](#linting)
+  - [Specifications](#specifications)
   - [Releasing](#releasing)
 - [Contributing](#contributing)
 - [License](#license)
@@ -138,6 +140,7 @@ end
 | `warnings`             | `Boolean`                       | `false` | Emit stderr warnings for synthesized params, skipped constraints |
 | `cross_field_group_limit` | `Integer`                    | `30`    | Cross-field groups larger than this are summarised on the endpoint |
 | `cross_field_messages` | `Hash`                          | `{}`    | Endpoint wording for summarised groups, keyed by `"METHOD /path"` |
+| `schema_paths`         | `Array<String>`                 | `[]`    | Directories searched for the JSON schema files named by `success schema:` |
 
 ### Annotations
 
@@ -339,6 +342,29 @@ A route that declares `success File` (with no `produces`) is treated as
 `application/octet-stream`, matching `grape-swagger`. An explicit `produces`
 takes precedence, so it can override that inference.
 
+### Schema-file responses
+
+A response that no entity builds (for example one assembled by a proxy) can be
+described by a JSON schema file instead:
+
+```ruby
+desc 'Run a query' do
+  success code: 200, schema: 'orbit/query_response'
+end
+```
+
+The name is looked up as `<name>.json` in each directory of `config.schema_paths`
+(first match wins). It may contain lowercase letters, digits, `_` and `/`. The
+file is emitted once under `components/schemas`, named by capitalizing each
+`/`- and `_`-separated part (`orbit/query_response` becomes `OrbitQueryResponse`),
+and referenced from the response. `is_array`, `example`, `examples` and `message`
+work as with `model:`, and `model:` wins when both are given. A missing or
+invalid file, or a component name that is already taken, raises
+`Gitlab::GrapeOpenapi::SchemaFileError`.
+
+The file must be an OpenAPI 3.0 Schema Object that JSON Schema validators also
+understand: no `$schema`, `$defs`, type arrays or `nullable`.
+
 ### Optional path segments
 
 Grape lets a route mark a path segment as optional with parentheses, e.g.
@@ -392,6 +418,18 @@ bundle exec rspec
 bundle exec rubocop
 ```
 
+### Specifications
+
+The gem's behaviour is specified with [OpenSpec](https://github.com/Fission-AI/OpenSpec)
+in [`openspec/specs/`](openspec/specs), one capability per directory. Changes to
+generated output start as an OpenSpec change proposal; see `CLAUDE.md` for the
+workflow.
+
+```bash
+npx -y @fission-ai/openspec@1.13.2 list --specs
+npx -y @fission-ai/openspec@1.13.2 validate --all --strict
+```
+
 ### Releasing
 
 Releases are driven by the

data/lib/gitlab/grape_openapi/configuration.rb

@@ -5,7 +5,7 @@ module Gitlab
     class Configuration
       attr_accessor :api_version, :api_prefix, :excluded_api_classes, :servers, :security_schemes, :info,
         :tag_overrides, :annotations, :coercer_mappings, :warnings,
-        :cross_field_group_limit, :cross_field_messages
+        :cross_field_group_limit, :cross_field_messages, :schema_paths
 
       def initialize
         @api_prefix = "api"
@@ -20,6 +20,7 @@ module Gitlab
         @annotations = {}
         @coercer_mappings = {}
         @warnings = false
+        @schema_paths = []
 
         # Cross field validations
         # Allow custom descriptions for endpoints whose groups of cross-validated

data/lib/gitlab/grape_openapi/converters/path_converter.rb

@@ -81,6 +81,17 @@ module Gitlab
             next unless definition
 
             EntityConverter.register(definition, @schema_registry)
+            register_schema_files(definition)
+          end
+        end
+
+        def register_schema_files(definition)
+          case definition
+          when Hash
+            return if EntityConverter.grape_entity?(definition[:model])
+
+            @schema_registry.register_file(definition[:schema]) if definition[:schema]
+          when Array then definition.each { |item| register_schema_files(item) }
           end
         end
 

data/lib/gitlab/grape_openapi/converters/response_converter.rb

@@ -63,14 +63,14 @@ module Gitlab
 
         def process_hash_entity(entity_hash)
           if entity_hash[:model] && EntityConverter.grape_entity?(entity_hash[:model])
-            status_code = entity_hash[:code] || infer_success_code(with_body: true)
             add_response_with_entity(
-              status_code: status_code,
-              description: entity_hash[:message] || http_status_text(status_code),
-              entity_class: entity_hash[:model],
-              example: entity_hash[:example],
-              examples: entity_hash[:examples],
-              is_array: entity_hash.fetch(:is_array, declared_is_array?)
+              **hash_response(entity_hash),
+              entity_class: entity_hash[:model]
+            )
+          elsif entity_hash[:schema]
+            add_response_with_entity(
+              **hash_response(entity_hash),
+              schema_name: SchemaRegistry.file_component_name(entity_hash[:schema])
             )
           else
             status_code = entity_hash[:code] || infer_success_code(with_body: declared_body?)
@@ -82,38 +82,28 @@ module Gitlab
           end
         end
 
+        def hash_response(entity_hash)
+          status_code = entity_hash[:code] || infer_success_code(with_body: true)
+          {
+            status_code: status_code,
+            description: entity_hash[:message] || http_status_text(status_code),
+            example: entity_hash[:example],
+            examples: entity_hash[:examples],
+            is_array: entity_hash.fetch(:is_array, declared_is_array?)
+          }
+        end
+
         def process_array_entities(entity_array)
           entity_array.each do |definition|
             case definition
             when Hash
-              process_array_hash_item(definition)
+              process_hash_entity(definition)
             when Class
               process_class_entity(definition)
             end
           end
         end
 
-        def process_array_hash_item(definition)
-          if definition[:model] && EntityConverter.grape_entity?(definition[:model])
-            status_code = definition[:code] || infer_success_code(with_body: true)
-            add_response_with_entity(
-              status_code: status_code,
-              description: definition[:message] || http_status_text(status_code),
-              entity_class: definition[:model],
-              example: definition[:example],
-              examples: definition[:examples],
-              is_array: definition.fetch(:is_array, declared_is_array?)
-            )
-          else
-            status_code = definition[:code] || infer_success_code(with_body: declared_body?)
-            add_simple_response(
-              status_code: status_code,
-              description: definition[:message] || http_status_text(status_code),
-              content: declared_content
-            )
-          end
-        end
-
         def extract_failure_responses
           explicit_codes = Array(@route.http_codes)
           defined_status_codes = explicit_codes.filter_map { |c| (c.is_a?(Hash) ? c[:code] : c[0])&.to_i }
@@ -136,11 +126,13 @@ module Gitlab
         end
 
         def add_response_with_entity(
-          status_code:, description:, entity_class:, example: nil, examples: nil, is_array: false)
+          status_code:, description:, entity_class: nil, schema_name: nil, example: nil, examples: nil,
+          is_array: false)
           response = Models::Response.new(
             status_code: status_code,
             description: description,
             entity_class: entity_class,
+            schema_name: schema_name,
             example: example,
             examples: examples,
             is_array: is_array

data/lib/gitlab/grape_openapi/models/response.rb

@@ -7,18 +7,21 @@ module Gitlab
       class Response
         attr_reader :status_code, :description, :entity_class, :headers, :content_type
 
+        # rubocop:disable Metrics/ParameterLists -- keyword arguments of a value object
         def initialize(
-          status_code:, description:, entity_class:, headers: {}, content_type: 'application/json',
-          example: nil, examples: nil, is_array: false)
+          status_code:, description:, entity_class: nil, schema_name: nil, headers: {},
+          content_type: 'application/json', example: nil, examples: nil, is_array: false)
           @status_code = status_code.to_s
           @description = description
           @entity_class = entity_class
+          @schema_name = schema_name
           @headers = headers
           @content_type = content_type
           @example = example
           @examples = examples
           @is_array = is_array
         end
+        # rubocop:enable Metrics/ParameterLists
 
         def to_h(schema_registry)
           response = {
@@ -49,7 +52,7 @@ module Gitlab
         end
 
         def schema_ref(schema_registry)
-          normalized_name = schema_registry.register(entity_class, nil)
+          normalized_name = @schema_name || schema_registry.register(entity_class, nil)
           "#/components/schemas/#{normalized_name}"
         end
       end

data/lib/gitlab/grape_openapi/schema_registry.rb

@@ -5,12 +5,42 @@ module Gitlab
     class SchemaRegistry
       attr_reader :schemas
 
+      SCHEMA_FILE_NAME = %r{\A[a-z0-9_]+(/[a-z0-9_]+)*\z}
+
+      def self.file_component_name(name)
+        name.to_s.split(%r{[/_]}).map(&:capitalize).join
+      end
+
       def initialize
         @schemas = {}
+        @file_paths = {}
+      end
+
+      # Registers the `<name>.json` schema found in `config.schema_paths` and
+      # returns its component name.
+      def register_file(name)
+        unless SCHEMA_FILE_NAME.match?(name.to_s)
+          raise SchemaFileError, "Invalid schema name #{name.inspect}: " \
+            "use lowercase letters, digits and underscores, with '/' between segments"
+        end
+
+        path = find_schema_file(name)
+        component = self.class.file_component_name(name)
+        return component if @file_paths[component] == path
+
+        raise SchemaFileError, "Schema #{name.inspect} collides with component #{component}" if @schemas.key?(component)
+
+        @schemas[component] = deep_freeze(parse_schema_file(path))
+        @file_paths[component] = path
+        component
       end
 
       def register(entity_class, schema)
         normalized_name = normalize_entity_class(entity_class)
+        if @file_paths.key?(normalized_name)
+          raise SchemaFileError, "Entity #{entity_class.name} collides with schema file component #{normalized_name}"
+        end
+
         return normalized_name if @schemas.key?(normalized_name)
         return normalized_name unless schema.is_a?(Models::Schema)
 
@@ -21,6 +51,34 @@ module Gitlab
       def normalize_entity_class(entity_class)
         entity_class.name.delete(':')
       end
+
+      private
+
+      def find_schema_file(name)
+        dirs = Gitlab::GrapeOpenapi.configuration.schema_paths
+        path = dirs.map { |dir| File.join(dir, "#{name}.json") }.find { |candidate| File.file?(candidate) }
+        return path if path
+
+        searched = dirs.empty? ? 'config.schema_paths is empty' : "searched #{dirs.join(', ')}"
+        raise SchemaFileError, "Schema file #{name.inspect} not found: #{searched}"
+      end
+
+      def parse_schema_file(path)
+        schema = JSON.parse(File.read(path))
+        return schema if schema.is_a?(Hash)
+
+        raise SchemaFileError, "Schema file #{path} must contain a JSON object"
+      rescue JSON::ParserError => e
+        raise SchemaFileError, "Schema file #{path} is not valid JSON: #{e.message}"
+      end
+
+      def deep_freeze(value)
+        case value
+        when Hash then value.each_value { |item| deep_freeze(item) }
+        when Array then value.each { |item| deep_freeze(item) }
+        end
+        value.freeze
+      end
     end
   end
 end

data/lib/gitlab/grape_openapi/version.rb

@@ -2,6 +2,6 @@
 
 module Gitlab
   module GrapeOpenapi
-    VERSION = "0.7.0"
+    VERSION = "0.8.0"
   end
 end

data/lib/gitlab-grape-openapi.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "json"
+
 require_relative "gitlab/grape_openapi/version"
 require_relative "gitlab/grape_openapi/grape_compat"
 require_relative "gitlab/grape_openapi/configuration"
@@ -59,6 +61,10 @@ module Gitlab
     # containing a named parameter (e.g. `/foo(/:a)/bar(/:b)`).
     MultipleOptionalSegmentsError = Class.new(GenerationError)
 
+    # Raised when a schema file named by a `success` declaration cannot be
+    # found, parsed or registered.
+    SchemaFileError = Class.new(GenerationError)
+
     class << self
       attr_writer :configuration
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-grape-openapi
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - group::api