rails_ninja 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c11362d2af26f7b911e310e2c67e603b5dfd63fd62e5758ce8936da06b1bb36
-  data.tar.gz: fb2bd66b8af63055d31a8c1cfc5eb2023883bc46f244c6f77fed0e0668dad4a8
+  metadata.gz: 9ea5b2dadb986f6d8ccde0b94cef6e57a941cd5336a776182e3462afc15dcdd7
+  data.tar.gz: 344e6aa870b08bb554fc239cc0f5f583721c8fd73d2d0532a9206d01cbe47cf0
 SHA512:
-  metadata.gz: e541dbca84d3e26df63229509abc3b5d70bae9da3ce6e8aa31da8c3a97a7df5d0f81ffd7e790820d96a019f0c16b984e2b329fc09fef5d0ea5b55c136c5b844c
-  data.tar.gz: '0381a91dd66a8c50be828018978d88d48e95b4f607325e94f1e4fb152d6714c79a79b2e6ef98e6c224c2d6a0409b96a061d748890edf188574e269a8a610b7d8'
+  metadata.gz: 22c2dcadc5aba38d8847721739a8562b7266a54ef6ad286b6cd4e4d35508c5127c0731bac09331e9fd9b7e460c25e95e002ba4bd8f42470f4b978f34db06f2bb
+  data.tar.gz: 54889989cb0f46f6e0fb2e5745aa02786361a604cc2a5006d44737dbbfe4f677d12f4964d7106a2e748530a67478224e51567b627e6ca90f43ffd1c7e5f92f9c

data/README.md

@@ -264,6 +264,73 @@ Deprecated paths remain routable and are marked as deprecated in OpenAPI.
 Set `server "https://api.example.com"` on an API to declare its server URL, or
 `docs false` to disable `/docs` and `/openapi.json`.
 
+## OpenAPI documentation in Ruby
+
+Declare descriptions, examples and parameter constraints next to the API schemas.
+The generator includes them in the JSON document without a separate overlay file.
+
+```ruby
+class InventoryApi < RailsNinja::API
+  title "Inventory API"
+  description "Read inventory records."
+  openapi_tag "Records", description: "Inventory records and their availability."
+
+  schema :Record, description: "One inventory record", example: { name: "Widget" } do
+    field :name, RailsNinja::Types::String,
+      description: "Display name", example: "Widget", openapi: { minLength: 1 }
+  end
+
+  schema :ReadError do
+    field :error, RailsNinja::Types::String, description: "Reason the read failed"
+  end
+
+  get "/records/:id",
+    operation_id: "getRecord",
+    summary: "Read an inventory record",
+    description: "Returns the record identified by the supplied ID.",
+    tags: ["Records"],
+    path_params: { id: { description: "Record ID", example: "123", schema: { pattern: "^[0-9]+$" } } },
+    responses: {
+      200 => Record,
+      429 => {
+        schema: ReadError,
+        description: "Wait before retrying the request.",
+        example: { error: "Too many requests" },
+        headers: { "Retry-After" => { description: "Seconds to wait", schema: { type: "integer" }, example: 1 } }
+      }
+    }
+  def read
+    # Fetch the record or render an error response.
+  end
+end
+```
+
+Schema classes can also declare `openapi description: ..., example: ...` inside
+their class body. Field `openapi:` accepts `format`, `pattern`, `minLength`,
+`maxLength`, `minimum`, `maximum`, `default`, `enum` and `oneOf`. These options
+describe constraints enforced by the application; they do not add runtime
+validation or change serialization. Field types and requiredness still come from
+the existing `field` declaration.
+
+GET, DELETE and HEAD request schemas supply query parameters. Their field
+descriptions and examples appear on the parameter, and their constraints appear
+in its schema. Header declarations accept `description:`, `example:` and
+`schema:` alongside `name:` and `required:`. Path annotations refer to the full
+mounted route, including parameters from a mount prefix. Path parameters remain
+required and retain their route names.
+
+For a request body, use `request_description:` on the endpoint. For each response,
+either keep the existing schema shorthand or supply a hash containing `schema:`
+and optional `description:`, `headers:` and `example:` or `examples:`. The two
+example forms are mutually exclusive. Named examples use OpenAPI Example Objects,
+for example `examples: { missing: { value: { error: "Not found" } } }`.
+Schemas can still be arrays or `one_of(...)` declarations.
+
+An explicit `operation_id:` keeps generated client method names stable when Ruby
+handler names change. Authors must choose unique IDs within each API document;
+deprecated route aliases omit the ID. API security descriptions belong in the
+existing `openapi_security_scheme` declaration.
+
 ## Static OpenAPI files
 
 Generate an OpenAPI 3.2 JSON file for every API:

data/lib/rails_ninja/api.rb

@@ -23,6 +23,20 @@ module RailsNinja
         @_title
       end
 
+      def description(value = nil)
+        @_description = value unless value.nil?
+        @_description
+      end
+
+      def openapi_tag(name, description:)
+        _openapi_tags.reject! { |tag| tag[:name] == name.to_s }
+        _openapi_tags << { name: name.to_s, description: description }
+      end
+
+      def _openapi_tags
+        @_openapi_tags ||= []
+      end
+
       def version(value = nil)
         if value
           @_version = value
@@ -85,6 +99,8 @@ module RailsNinja
         super
         subclass.instance_variable_set(:@_openapi_security_schemes, _openapi_security_schemes.transform_values(&:dup))
         subclass.instance_variable_set(:@_openapi_security, _openapi_security.dup)
+        subclass.instance_variable_set(:@_openapi_tags, _openapi_tags.deep_dup)
+        subclass.instance_variable_set(:@_description, description&.dup)
         RailsNinja.registered_apis << subclass
       end
 

data/lib/rails_ninja/endpoint_group.rb

@@ -22,8 +22,9 @@ module RailsNinja
       end
 
       # Schema definition DSL
-      def schema(name, &block)
+      def schema(name, **documentation, &block)
         klass = Class.new(Schema::Base)
+        klass.openapi(**documentation)
         klass.class_eval(&block)
 
         # Register as a constant on this class so it's accessible by name

data/lib/rails_ninja/openapi/generator.rb

@@ -33,10 +33,12 @@ module RailsNinja
           components: components,
         }
         spec[:servers] = [{ url: @api_class._server }] if @api_class._server
+        spec[:info][:description] = @api_class.description if @api_class.description
+        spec[:tags] = @api_class._openapi_tags if @api_class._openapi_tags.any?
         if @api_class._openapi_security.any?
           spec[:security] = @api_class._openapi_security.map { |name| { name => [] } }
         end
-        spec
+        spec.deep_dup
       end
 
       def to_json(*_args)
@@ -79,18 +81,22 @@ module RailsNinja
             body_verb = %w[get delete head].exclude?(verb)
 
             operation = { summary: endpoint.summary }
+            operation[:description] = endpoint.description if endpoint.description
             operation[:tags] = endpoint.tags if endpoint.tags&.any?
             operation[:responses] = build_responses(endpoint)
             # Deprecated aliases share a handler with the primary endpoint; only the
             # current path carries the operationId to keep it unique across the spec.
-            operation[:operationId] = build_operation_id(endpoint) unless endpoint.deprecated?
+            operation[:operationId] = endpoint.operation_id || build_operation_id(endpoint) unless endpoint.deprecated?
             operation[:deprecated] = true if endpoint.deprecated?
 
             if endpoint.request_schema && body_verb
               operation[:requestBody] = build_request_body(endpoint.request_schema)
+              if endpoint.request_description
+                operation[:requestBody][:description] = endpoint.request_description
+              end
             end
 
-            params = extract_path_params(path) + extract_header_params(endpoint)
+            params = extract_path_params(path, endpoint.path_params) + extract_header_params(endpoint)
             params += extract_query_params(endpoint) unless body_verb
             operation[:parameters] = params if params.any?
 
@@ -113,6 +119,9 @@ module RailsNinja
             description: response_description_for(status),
             content: { "application/json" => { schema: schema_node } },
           }
+          documentation = endpoint.response_documentation.fetch(status, {})
+          out[status.to_s].merge!(documentation.slice(:description, :headers))
+          out[status.to_s][:content]["application/json"].merge!(documentation.slice(:example, :examples))
         end
       end
 
@@ -188,9 +197,16 @@ module RailsNinja
         end
       end
 
-      def extract_path_params(path)
-        path.scan(/:(\w+)/).flatten.map do |param|
-          { name: param, in: "path", required: true, schema: { type: "string" } }
+      def extract_path_params(path, documentation)
+        names = path.scan(/:(\w+)/).flatten
+        unknown = documentation.keys - names
+        raise ArgumentError, "Unknown path parameter annotations: #{unknown.join(', ')}" if unknown.any?
+
+        names.map do |param|
+          metadata = documentation.fetch(param, {})
+          { name: param, in: "path", required: true,
+            schema: { type: "string" }.merge(metadata.fetch(:schema, {})) }
+            .merge(metadata.slice(:description, :example))
         end
       end
 
@@ -198,7 +214,9 @@ module RailsNinja
         return [] unless endpoint.request_schema
 
         endpoint.request_schema._fields.map do |name, field|
-          { name: name.to_s, in: "query", required: field.required, schema: schema_ref(field.type) }
+          { name: name.to_s, in: "query", required: field.required,
+            schema: schema_ref(field.type).merge(field.documentation.except(:description, :example)) }
+            .merge(field.documentation.slice(:description, :example))
         end
       end
 
@@ -207,6 +225,7 @@ module RailsNinja
 
         endpoint.header_params.map do |h|
           { name: h[:name], in: "header", required: h[:required], schema: h[:schema] }
+            .merge(h.slice(:description, :example))
         end
       end
 
@@ -261,16 +280,17 @@ module RailsNinja
         required = []
 
         schema_class._fields.each do |name, field|
-          property = schema_ref(field.type)
+          property = schema_ref(field.type).deep_dup
           property[:title] = schema_title(name)
           property[:enum] = field.enum if field.enum
+          property.merge!(field.documentation)
           properties[name.to_s] = property
           required << name.to_s if field.required
         end
 
         result = { type: "object", title: schema_name(schema_class), properties: properties }
         result[:required] = required if required.any?
-        result
+        result.merge(schema_class.openapi)
       end
 
       def schema_title(name)

data/lib/rails_ninja/openapi/schema_ref.rb

@@ -24,13 +24,13 @@ module RailsNinja
         required = []
 
         schema_class._fields.each do |name, field|
-          properties[name.to_s] = to_json_schema(field.type)
+          properties[name.to_s] = to_json_schema(field.type).merge(field.documentation)
           required << name.to_s if field.required
         end
 
         result = { type: "object", properties: properties }
         result[:required] = required if required.any?
-        result
+        result.merge(schema_class.openapi).deep_dup
       end
 
       def primitive_type(type)

data/lib/rails_ninja/operation.rb

@@ -3,21 +3,44 @@
 module RailsNinja
   class Operation
     attr_reader :verb, :path, :handler, :display_handler, :api_class,
-                :request_schema, :responses_map, :tags, :summary, :header_params
+                :request_schema, :responses_map, :tags, :summary, :header_params,
+                :description, :operation_id, :path_params, :request_description, :response_documentation
 
     def initialize(verb:, path:, handler:, api_class:, request: nil, response: nil, responses: nil,
-      tags: nil, summary: nil, headers: nil, deprecated: false)
+      tags: nil, summary: nil, headers: nil, deprecated: false, description: nil,
+      operation_id: nil, path_params: {}, request_description: nil)
       @verb = verb
       @path = path
       @handler = handler
       @display_handler = handler
       @api_class = api_class
       @request_schema = request
-      @responses_map = responses || (response ? { 200 => response } : {})
+      @response_documentation = {}
+      @responses_map = (responses || (response ? { 200 => response } : {})).to_h do |status, declaration|
+        if declaration.is_a?(Hash)
+          unknown = declaration.keys - %i[schema description example examples headers]
+          raise ArgumentError, "Unsupported response #{status} keys: #{unknown.join(', ')}" if unknown.any?
+          if declaration.key?(:example) && declaration.key?(:examples)
+            raise ArgumentError, "Response #{status} cannot declare both example and examples"
+          end
+          @response_documentation[status] = declaration.except(:schema).deep_dup
+          [status, declaration.fetch(:schema)]
+        else
+          [status, declaration]
+        end
+      end
       @tags = tags || api_class._tags || []
       @summary = summary || handler.to_s.tr("_", " ").capitalize
       @header_params = merge_headers(api_class._headers, headers)
       @deprecated = deprecated
+      @description = description
+      @operation_id = operation_id
+      @path_params = path_params.transform_keys(&:to_s).deep_dup
+      @path_params.each_value do |metadata|
+        unknown = metadata.keys - %i[description example schema]
+        raise ArgumentError, "Unsupported path parameter keys: #{unknown.join(', ')}" if unknown.any?
+      end
+      @request_description = request_description
     end
 
     def deprecated?
@@ -64,7 +87,9 @@ module RailsNinja
         if h.is_a?(String)
           { name: h, required: true, schema: { type: "string" } }
         elsif h.is_a?(Hash)
-          { name: h[:name], required: h.fetch(:required, true), schema: { type: h.fetch(:type, "string") } }
+          { name: h[:name], required: h.fetch(:required, true),
+            schema: h.fetch(:schema, { type: h.fetch(:type, "string") }) }
+            .merge(h.slice(:description, :example)).deep_dup
         end
       end
     end

data/lib/rails_ninja/schema/field.rb

@@ -2,9 +2,16 @@
 
 module RailsNinja
   module Schema
-    Field = Struct.new(:name, :type, :required, :default, :enum, keyword_init: true) do
-      def initialize(name:, type:, required: true, default: nil, enum: nil)
-        super
+    Field = Struct.new(:name, :type, :required, :default, :enum, :documentation, keyword_init: true) do
+      def initialize(name:, type:, required: true, default: nil, enum: nil, openapi: {}, **documentation)
+        unknown = openapi.keys - %i[format pattern minLength maxLength minimum maximum default enum oneOf]
+        raise ArgumentError, "Unsupported field OpenAPI keys: #{unknown.join(', ')}" if unknown.any?
+
+        unknown = documentation.keys - %i[description example]
+        raise ArgumentError, "Unsupported field documentation keys: #{unknown.join(', ')}" if unknown.any?
+
+        super(name: name, type: type, required: required, default: default, enum: enum,
+          documentation: openapi.merge(documentation).deep_dup)
       end
     end
   end

data/lib/rails_ninja/schema.rb

@@ -4,14 +4,15 @@ module RailsNinja
   module Schema
     class Base
       class << self
-        def field(name, type, required: true, default: nil, enum: nil)
+        def field(name, type, required: true, default: nil, enum: nil, **documentation)
           validate_type!(type)
           _fields[name.to_sym] = Field.new(
             name: name.to_sym,
             type: type,
             required: required,
             default: default,
-            enum: enum
+            enum: enum,
+            **documentation
           )
         end
 
@@ -23,9 +24,18 @@ module RailsNinja
           @_fields ||= {}
         end
 
+        def openapi(**documentation)
+          unknown = documentation.keys - %i[description example]
+          raise ArgumentError, "Unsupported schema documentation keys: #{unknown.join(', ')}" if unknown.any?
+
+          @_openapi ||= {}
+          @_openapi.merge!(documentation.deep_dup)
+        end
+
         def inherited(subclass)
           super
           subclass.instance_variable_set(:@_fields, _fields.dup)
+          subclass.instance_variable_set(:@_openapi, openapi.deep_dup)
         end
 
         def validate(data)

data/lib/rails_ninja/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsNinja
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/rails_ninja.rb

@@ -3,6 +3,7 @@
 require "action_controller/metal"
 require "active_support/core_ext/array/wrap"
 require "active_support/core_ext/enumerable"
+require "active_support/core_ext/object/deep_dup"
 require "rack"
 require "multi_json"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_ninja
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Benjamin Urrutia
@@ -167,7 +167,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Django Ninja-inspired API framework for Ruby/Rails
 test_files: []